diff --git a/vizro-ai/CHANGELOG.md b/vizro-ai/CHANGELOG.md
index 72186c8b1..98a162904 100644
--- a/vizro-ai/CHANGELOG.md
+++ b/vizro-ai/CHANGELOG.md
@@ -141,5 +141,4 @@ See the fragment files in the [changelog.d directory](https://github.com/mckinse
## Highlights ✨
-- Initial release of Vizro-AI package. Vizro-AI is a tool for generating data
- visualizations. ([#138](https://github.com/mckinsey/vizro/pull/138))
+- Initial release of Vizro-AI package. Vizro-AI is a tool for generating data visualizations. ([#138](https://github.com/mckinsey/vizro/pull/138))
diff --git a/vizro-ai/README.md b/vizro-ai/README.md
index 888b79af8..faed6c79a 100644
--- a/vizro-ai/README.md
+++ b/vizro-ai/README.md
@@ -2,11 +2,7 @@
-[](https://pypi.org/project/vizro/)
-[](https://badge.fury.io/py/vizro_ai)
-[](https://github.com/mckinsey/vizro/blob/main/LICENSE.md)
-[](https://vizro-ai.readthedocs.io/)
-[](https://www.bestpractices.dev/projects/7858)
+[](https://pypi.org/project/vizro/) [](https://badge.fury.io/py/vizro_ai) [](https://github.com/mckinsey/vizro/blob/main/LICENSE.md) [](https://vizro-ai.readthedocs.io/) [](https://www.bestpractices.dev/projects/7858)
diff --git a/vizro-ai/changelog.d/20240917_174515_alexey_snigir_automatic_vizro_ai_score_tests.md b/vizro-ai/changelog.d/20240917_174515_alexey_snigir_automatic_vizro_ai_score_tests.md
index f1f65e73c..aa45b72f1 100644
--- a/vizro-ai/changelog.d/20240917_174515_alexey_snigir_automatic_vizro_ai_score_tests.md
+++ b/vizro-ai/changelog.d/20240917_174515_alexey_snigir_automatic_vizro_ai_score_tests.md
@@ -10,36 +10,42 @@ Uncomment the section that is right (remove the HTML comment wrapper).
- 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))
-->
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
@@ -17,14 +16,11 @@ and are responsible for obtaining their own suitable API key for the relevant mo
Users acknowledge and agree that:
-Any results, options, data, recommendations, analyses, code,
-or other information (“Outputs”) generated by any third-party generative AI tools (“GenAI Tools”) may contain some inaccuracies, biases, illegitimate, potentially infringing,
-or otherwise inappropriate content that may be mistaken, discriminatory, or misleading.
+Any results, options, data, recommendations, analyses, code, or other information (“Outputs”) generated by any third-party generative AI tools (“GenAI Tools”) may contain some inaccuracies, biases, illegitimate, potentially infringing, or otherwise inappropriate content that may be mistaken, discriminatory, or misleading.
McKinsey & Company:
-(i) expressly disclaims the accuracy, adequacy, timeliness, reliability, merchantability, fitness for a particular purpose, non-infringement,
-safety or completeness of any Outputs,
+(i) expressly disclaims the accuracy, adequacy, timeliness, reliability, merchantability, fitness for a particular purpose, non-infringement, safety or completeness of any Outputs,
(ii) shall not be liable for any errors, omissions, or other defects in, delays or interruptions in such Outputs, or for any actions taken in reliance thereon, and
@@ -32,7 +28,6 @@ safety or completeness of any Outputs,
The Outputs shall be verified and validated by the users and shall not be used without human oversight and as a sole basis for making decisions impacting individuals.
-Users remain solely responsible for the use of the Output, in particular, the users will need to determine the level of human oversight needed to be given the context and use case,
-as well as for informing the users’ personnel and other affected users about the nature of the GenAI Output.
-Users are also fully responsible for their decisions, actions, use of Vizro and Vizro-AI and compliance with applicable laws, rules, and regulations, including but not limited to confirming that the Outputs do not infringe any third-party rights.
+Users remain solely responsible for the use of the Output, in particular, the users will need to determine the level of human oversight needed to be given the context and use case, as well as for informing the users’ personnel and other affected users about the nature of the GenAI Output. Users are also fully responsible for their decisions, actions, use of Vizro and Vizro-AI and compliance with applicable laws, rules, and regulations, including but not limited to confirming that the Outputs do not infringe any third-party rights.
+
diff --git a/vizro-ai/docs/pages/explanation/faq.md b/vizro-ai/docs/pages/explanation/faq.md
index 46dfcd2ce..9eb0fad6f 100644
--- a/vizro-ai/docs/pages/explanation/faq.md
+++ b/vizro-ai/docs/pages/explanation/faq.md
@@ -3,20 +3,11 @@
## Who works on Vizro-AI?
### Current team members
-[Alexey Snigir](https://github.com/l0uden),
-[Anna Xiong](https://github.com/Anna-Xiong),
-[Antony Milne](https://github.com/antonymilne),
-[Dan Dumitriu](https://github.com/dandumitriu1),
-[Huong Li Nguyen](https://github.com/huong-li-nguyen),
-[Jo Stichbury](https://github.com/stichbury),
-[Joseph Perkins](https://github.com/Joseph-Perkins),
-[Lingyi Zhang](https://github.com/lingyielia),
-[Maximilian Schulz](https://github.com/maxschulz-COL),
-[Nadija Graca](https://github.com/nadijagraca),
-[Petar Pejovic](https://github.com/petar-qb).
-With thanks to Sam Bourton and Stephen Xu for sponsorship, inspiration and guidance, plus everyone else who helped to test, guide, support and encourage development.
+[Alexey Snigir](https://github.com/l0uden), [Anna Xiong](https://github.com/Anna-Xiong), [Antony Milne](https://github.com/antonymilne), [Dan Dumitriu](https://github.com/dandumitriu1), [Huong Li Nguyen](https://github.com/huong-li-nguyen), [Jo Stichbury](https://github.com/stichbury), [Joseph Perkins](https://github.com/Joseph-Perkins), [Lingyi Zhang](https://github.com/lingyielia), [Maximilian Schulz](https://github.com/maxschulz-COL), [Nadija Graca](https://github.com/nadijagraca), [Petar Pejovic](https://github.com/petar-qb).
+With thanks to Sam Bourton and Stephen Xu for sponsorship, inspiration and guidance, plus everyone else who helped to test, guide, support and encourage development.
## Which large language models are supported by vizro-ai?
+
Refer to [supported models](../user-guides/customize-vizro-ai.md#supported-models) in `vizro-ai` docs.
diff --git a/vizro-ai/docs/pages/explanation/safeguard.md b/vizro-ai/docs/pages/explanation/safeguard.md
index f4311fcd6..aacd2c503 100644
--- a/vizro-ai/docs/pages/explanation/safeguard.md
+++ b/vizro-ai/docs/pages/explanation/safeguard.md
@@ -1,88 +1,74 @@
# Safeguard dynamic code execution in Vizro-AI
-Vizro-AI uses the `exec()` statement in Python to run generated code from large language models (LLMs) for
-self-debugging and automatic visual rendering in methods such as `.get_fig_object()` and `VizroAI.plot()`.
-One of the primary concerns is the potential for malicious code to access or change critical system resources or data.
+Vizro-AI uses the `exec()` statement in Python to run generated code from large language models (LLMs) for self-debugging and automatic visual rendering in methods such as `.get_fig_object()` and `VizroAI.plot()`. One of the primary concerns is the potential for malicious code to access or change critical system resources or data.
## Understand `exec()`
-The `exec()` function enables the dynamic execution of Python programs which can either be a string or object code.
-While it offers great flexibility, it also poses a significant security risk, especially when executing untrusted code.
+The `exec()` function enables the dynamic execution of Python programs which can either be a string or object code. While it offers great flexibility, it also poses a significant security risk, especially when executing untrusted code.
## Safeguarding code execution
-While we have made considerable efforts to safeguard its usage by limiting the usage to specific modules and functions and by restricting certain built-in operations,
-these measures cannot guarantee absolute security. It is imperative for users to take extra precautions.
+While we have made considerable efforts to safeguard its usage by limiting the usage to specific modules and functions and by restricting certain built-in operations, these measures cannot guarantee absolute security. It is imperative for users to take extra precautions.
### Our effort on safeguarding code execution in Vizro-AI
-To help to mitigate these risks, we limit the execution of certain modules and functions.
-One approach is to use Python's built-in `sys` module to restrict access to unsafe modules or functions.
-By defining a whitelist of safe modules and packages and restricting certain built-in functions.
+To help to mitigate these risks, we limit the execution of certain modules and functions. One approach is to use Python's built-in `sys` module to restrict access to unsafe modules or functions. By defining a whitelist of safe modules and packages and restricting certain built-in functions.
!!! Warning
-
- While some measures have been put in place to help safeguard against known vulnerabilities,
- it is important to run such systems in an isolated environment and avoid providing malicious inputs,
- since such **safeguards can never be 100% effective**. Always ensure the security infrastructure when implementing and using such systems.
+ While some measures have been put in place to help safeguard against known vulnerabilities, it is important to run such systems in an isolated environment and avoid providing malicious inputs, since such **safeguards can never be 100% effective**. Always ensure the security infrastructure when implementing and using such systems.
The white lists indicate allowed packages and built-in functions.
- The red lists represent potentially
- unsafe methods or operations that are restricted.
+ The red lists represent potentially unsafe methods or operations that are restricted.
The lists below are a reflection of the security and functionality we have implemented with Vizro-AI:
-??? success "Whitelisted Packages"
+
- - `pandas`
- - `numpy`
- - `vizro`
- - `plotly`
- - `datetime`
- - `matplotlib`
- - `dash`
- - `scipy`
- - `sklearn`
+??? success "Whitelisted Packages"
+ - `pandas`
+ - `numpy`
+ - `vizro`
+ - `plotly`
+ - `datetime`
+ - `matplotlib`
+ - `dash`
+ - `scipy`
+ - `sklearn`
??? success "Whitelisted Builtins"
-
- - abs
- - len
- - max
- - min
- - print
- - sum
- - None
- - False
- - True
- - dict
- - enumerate
- - float
- - int
- - list
- - map
- - str
- - tuple
+ - abs
+ - len
+ - max
+ - min
+ - print
+ - sum
+ - None
+ - False
+ - True
+ - dict
+ - enumerate
+ - float
+ - int
+ - list
+ - map
+ - str
+ - tuple
??? failure "Redlisted Class Methods"
-
- subclasses
- builtins
??? failure "Redlisted Data Handling Methods and Formats"
-
- Various data file formats (such as .csv, .tsv, .xlsx, .json, and so on)
- Specific methods related to data input/output operations (such as .to_csv, .read_excel, .loadtxt)
+
+
### Safeguard for user environment and input
-- **Isolated environment**: Always run code in an isolated or contained environment, such as a virtual environment,
- virtual machine or container, to minimize potential harm to the primary system.
+- **Isolated environment**: Always run code in an isolated or contained environment, such as a virtual environment, virtual machine or container, to minimize potential harm to the primary system.
-- **Avoid malicious input**: Never feed untrusted or malicious input. Regardless of safeguards,
- there's always a risk associated with executing dynamic code.
- It remains the user's responsibility to ensure the safety and appropriateness of executing any generated code,
- particularly in sensitive or critical contexts.
+- **Avoid malicious input**: Never feed untrusted or malicious input. Regardless of safeguards, there's always a risk associated with executing dynamic code. It remains the user's responsibility to ensure the safety and appropriateness of executing any generated code, particularly in sensitive or critical contexts.
- **Accessible to trusted users**: Only trusted users should be given access to the system to run Vizro-AI.
diff --git a/vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md b/vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md
index 489e5aa33..fc54596bb 100644
--- a/vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md
+++ b/vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md
@@ -4,60 +4,63 @@ Vizro-AI uses generative AI models because large language models (LLMs) represen
We recommend users research and understand the selected model before using `vizro_ai` package.
-Users are encouraged to treat AI-generated content as supplementary, **always apply human judgment**,
-approach with caution, review the relevant [disclaimer](disclaimer.md) page, and consider the following:
+Users are encouraged to treat AI-generated content as supplementary, **always apply human judgment**, approach with caution, review the relevant [disclaimer](disclaimer.md) page, and consider the following:
+
+
### 1. Hallucination and misrepresentation
Generative models can potentially generate information while appearing factual, being entirely fictitious or misleading.
+
-The vendor models might lack real-time knowledge or events beyond its last updates.
-`vizro_ai` output may vary and you should always verify critical information.
-It is the user's responsibility to discern the accuracy, consistent, and reliability of the generated content.
+
+The vendor models might lack real-time knowledge or events beyond its last updates. `vizro_ai` output may vary and you should always verify critical information. It is the user's responsibility to discern the accuracy, consistent, and reliability of the generated content.
+
### 2. Unintended and sensitive output
+
-The outputs from these models can be unexpected, inappropriate, or even harmful.
-Users as human in the loop is an essential part. Users must check and interpret the final output.
-It is necessary to approach the generated content with caution, especially when shared or applied in various contexts.
+
+The outputs from these models can be unexpected, inappropriate, or even harmful. Users as human in the loop is an essential part. Users must check and interpret the final output. It is necessary to approach the generated content with caution, especially when shared or applied in various contexts.
+
### 3. Data privacy
+
-Your data is sent to model vendors if you connect to LLMs via their APIs.
-For example, if you connect to the model from OpenAI, your data will be sent to OpenAI via their API.
-Users should be cautious about sharing or inputting any personal or sensitive information.
+
+Your data is sent to model vendors if you connect to LLMs via their APIs. For example, if you connect to the model from OpenAI, your data will be sent to OpenAI via their API. Users should be cautious about sharing or inputting any personal or sensitive information.
+
### 4. Bias and fairness
+
-Generative AI can exhibit biases present in their training data.
-Users need to be aware of and navigate potential biases in generated outputs and be cautious when interpreting the generated content.
+
+Generative AI can exhibit biases present in their training data. Users need to be aware of and navigate potential biases in generated outputs and be cautious when interpreting the generated content.
+
### 5. Malicious use
+
+
These models can be exploited for various malicious activities. Users should be cautious about how and where they deploy and access such models.
It's crucial for users to remain informed, cautious, and ethical in their applications.
-
## Dependencies, code scanners, and information security
-It may occur that dependencies of `vizro_ai` get flagged by code scanners and other information security tools. As a consequence it may happen that
-`vizro_ai` also get flagged.
+It may occur that dependencies of `vizro_ai` get flagged by code scanners and other information security tools. As a consequence it may happen that `vizro_ai` also get flagged.
-While we aim to resolve any flagged issues as soon as possible, there may not always be an immediate available fix, especially in a dynamic environment such as generative AI. We encourage users to investigate if any flagged information security issues are actually related
-to any functionality used in our code base or if they only concern functionality outside the scope of `vizro_ai`.
+While we aim to resolve any flagged issues as soon as possible, there may not always be an immediate available fix, especially in a dynamic environment such as generative AI. We encourage users to investigate if any flagged information security issues are actually related to any functionality used in our code base or if they only concern functionality outside the scope of `vizro_ai`.
In case those issues are related to code execution, note that `vizro_ai` has its own process of executing dynamic code (see [Safeguard Execution of Dynamic Code](safeguard.md)), and does not rely on its dependencies to do so.
-
## Execution of dynamic code in Vizro-AI
-The `exec()` statement is used in `vizro_ai`. It enables dynamic execution of Python programs which can be powerful, but can also pose security risk
-if used without caution. When paired with outputs from generative models, there is potential for unintended or malicious code execution.
+The `exec()` statement is used in `vizro_ai`. It enables dynamic execution of Python programs which can be powerful, but can also pose security risk if used without caution. When paired with outputs from generative models, there is potential for unintended or malicious code execution.
Users must exercise caution when executing code generated by or influenced by AI models. It's essential to:
@@ -69,11 +72,9 @@ Users must exercise caution when executing code generated by or influenced by AI
To learn more, refer to the section that describes how to [safeguard execution of dynamic code](safeguard.md).
-
## Debugging in Vizro-AI with LangSmith and LangFuse
-[LangSmith](https://docs.smith.langchain.com/) and [LangFuse](https://langfuse.com/docs) are tools designed to enhance transparency and interpretability in AI workflows.
-To improve debugging and traceability, you can use the advanced observability and evaluation features of these tools with Vizro-AI.
+[LangSmith](https://docs.smith.langchain.com/) and [LangFuse](https://langfuse.com/docs) are tools designed to enhance transparency and interpretability in AI workflows. To improve debugging and traceability, you can use the advanced observability and evaluation features of these tools with Vizro-AI.
To ensure responsible use, review their data privacy and security policies. See [LangFuse Data Security & Privacy ](https://langfuse.com/docs/data-security-privacy) and [LangSmith Privacy Policy](https://www.langchain.com/privacy-policy) site for more details.
diff --git a/vizro-ai/docs/pages/tutorials/quickstart-dashboard.md b/vizro-ai/docs/pages/tutorials/quickstart-dashboard.md
index c29607baa..2118112d7 100644
--- a/vizro-ai/docs/pages/tutorials/quickstart-dashboard.md
+++ b/vizro-ai/docs/pages/tutorials/quickstart-dashboard.md
@@ -8,12 +8,11 @@ You may also want to review the [Vizro dashboard tutorial](https://vizro.readthe
If you haven't already installed Vizro-AI and set up the API key for OpenAI, follow the [installation guide](../user-guides/install.md).
-
## 2. Open a Notebook
+
A good way to initially explore Vizro-AI is from inside a Jupyter Notebook.
??? "If you haven't used Jupyter before..."
-
You may need to install the Jupyter package if you . From the terminal window:
```bash
@@ -39,6 +38,7 @@ print(vizro_ai.__version__)
You should see a return output of the form `x.y.z`.
## 3. Instantiate VizroAI
+
```py
from vizro_ai import VizroAI
@@ -46,6 +46,7 @@ vizro_ai = VizroAI()
```
## 4. Prepare the data
+
Next, prepare the data to pass to Vizro-AI. In this example, we use the [gapminder data](https://plotly.com/python-api-reference/generated/plotly.express.data.html#plotly.express.data.gapminder).
```py
@@ -87,6 +88,7 @@ dashboard = vizro_ai.dashboard([df], user_question)
The call to `dashboard()` initiates dashboard generation. By default, it generates the Vizro `Dashboard` Object.
## 7. Build dashboard
+
Once dashboard generation is complete, launch the dashboard with `build()`.
```py
@@ -95,7 +97,6 @@ Vizro().build(dashboard).run()
```
!!! example "Generated dashboard"
-
=== "Code for the cell"
```py
from vizro import Vizro
@@ -119,6 +120,6 @@ Vizro().build(dashboard).run()
```
=== "Result"
- [![VizroAIDashboardPage1]][VizroAIDashboardPage1]
+ [![VizroAIDashboardPage1]][vizroaidashboardpage1]
- [VizroAIDashboardPage1]: ../../assets/tutorials/dashboard/dashboard0_page1.png
+[vizroaidashboardpage1]: ../../assets/tutorials/dashboard/dashboard0_page1.png
diff --git a/vizro-ai/docs/pages/tutorials/quickstart.md b/vizro-ai/docs/pages/tutorials/quickstart.md
index 17d673927..64574cd77 100644
--- a/vizro-ai/docs/pages/tutorials/quickstart.md
+++ b/vizro-ai/docs/pages/tutorials/quickstart.md
@@ -1,20 +1,24 @@
# Chart generation
+
This tutorial introduces you to chart generation using Vizro-AI. It explains the basics of creating a plotly chart that can be added to a Vizro dashboard. When you have followed it, you are set up to explore the Vizro and Vizro-AI packages further.
+
### 1. Install Vizro-AI and its dependencies
+
If you haven't already installed Vizro-AI and set up the API key for OpenAI, follow the [installation guide](../user-guides/install.md).
+
### 2. Open a Jupyter Notebook
+
A good way to initially explore Vizro-AI is from inside a Jupyter Notebook.
??? "If you haven't used Jupyter before..."
-
You may need to install the Jupyter package if you . From the terminal window:
```bash
@@ -40,7 +44,9 @@ print(vizro_ai.__version__)
You should see a return output of the form `x.y.z`.
+
### 3. Create your first plotly chart using Vizro-AI
+
Let's create a chart to illustrate the GDP of various continents while including a reference line for the average. We give Vizro-AI the English language instruction "*describe the composition of GDP in continent and color by continent, and add a horizontal line for avg GDP*".
@@ -54,12 +60,12 @@ import vizro.plotly.express as px
df = px.data.gapminder()
```
-
Next, we instantiate `VizroAI`:
```python
vizro_ai = VizroAI()
```
+
To learn how to customize the `VizroAI` class, check out the guide on [how to customize models](../user-guides/customize-vizro-ai.md).
Finally, we call the `plot()` method with our English language instruction, to generate the visualization:
@@ -74,7 +80,6 @@ vizro_ai.plot(
```
!!! warning "Help! The LLM request was unauthorized"
-
If you see an error similar to this, your LLM API key is not valid:
`INFO:httpx:HTTP Request: POST https://api.openai.com/v1/chat/completions "HTTP/1.1 401 Unauthorized"`
@@ -83,12 +88,11 @@ vizro_ai.plot(
`export OPENAI_API_KEY="sk-YOURKEY"`.
- The call above makes the API key available from that terminal instance. If you want to access Vizro-AI from a Notebook, you should then run `jupyter notebook` (or just work within that terminal to run your Python script in `app.py`. When you restart the terminal, you'll need to call `export` again.
+ The call above makes the API key available from that terminal instance. If you want to access Vizro-AI from a Notebook, you should then run `jupyter notebook` (or just work within that terminal to run your Python script in `app.py`. When you restart the terminal, you'll need to call `export` again.
And that's it! By passing the prepared data and written visualization request, Vizro-AI takes care of the processing. It generates the necessary code for data manipulation and chart creation, and returns the chart by executing the generated code.
!!! example "Vizro-AI Syntax"
-
=== "Code for the cell"
```py
import vizro.plotly.express as px
@@ -104,38 +108,40 @@ And that's it! By passing the prepared data and written visualization request, V
Make sure to take average over continent.""",
)
```
- === "Result"
- [![LineGraph]][LineGraph]
- [LineGraph]: ../../assets/tutorials/chart/GDP_Composition_Graph.png
+ === "Result"
+ [![LineGraph]][linegraph]
The chart created is interactive: you can hover over the data for more information.
Passing `return_elements=True` to the `plot()` method returns an object, which includes the code along with a set of insights to explain the rendered chart in detail. You can then use the code within a Vizro dashboard as illustrated in the [Vizro documentation](https://vizro.readthedocs.io/en/stable/pages/tutorials/explore-components/#22-add-further-components). For the line graph above, the code returned may be as follows:
!!! example "Returned by Vizro-AI"
-
```python
from vizro.models.types import capture
import vizro.plotly.express as px
import pandas as pd
- @capture('graph')
+
+
+ @capture("graph")
def custom_chart(data_frame):
- df = data_frame.groupby(['year', 'continent'])['gdpPercap'].mean().unstack().reset_index()
- fig = px.line(df, x='year', y=['Africa', 'Americas', 'Asia', 'Europe', 'Oceania'])
+ df = data_frame.groupby(["year", "continent"])["gdpPercap"].mean().unstack().reset_index()
+ fig = px.line(df, x="year", y=["Africa", "Americas", "Asia", "Europe", "Oceania"])
return fig
+
fig = custom_chart(data_frame=df)
```
+
### 4. Get an explanation with your chart
+
Let's create another example to illustrate the code and insights returned when passing `return_elements=True` as a parameter to `plot()`:
!!! example "Specify `return_elements=True`"
-
=== "Code for the cell"
```py
res = vizro_ai.plot(df, "show me the geo distribution of life expectancy", return_elements=True)
@@ -143,8 +149,10 @@ Let's create another example to illustrate the code and insights returned when p
print(res.chart_insights)
print(res.code_explanation)
```
+
=== "Result"
Code
+
```py
import plotly.express as px
@@ -164,13 +172,17 @@ Let's create another example to illustrate the code and insights returned when p
)
return fig
```
+
Chart insights
+
```
This choropleth map visualizes the global distribution of life expectancy across
different countries. It highlights variations and trends in life expectancy,
providing a clear visual representation of geographical disparities.
```
+
Code explanation
+
```
- Import Plotly Express.
- Create a choropleth map using the `px.choropleth` function.
@@ -180,13 +192,14 @@ Let's create another example to illustrate the code and insights returned when p
- Update layout to enhance map readability and aesthetics.
```
- [GeoDistribution]: ../../assets/tutorials/chart/GeoDistribution.png
-
+
### 5. Explore further
-
+
Congratulations! You have created your first charts with Vizro-AI and you are ready to explore further.
A good place to start would be to review the different how-to guides to learn [the different ways to run Vizro-AI](../user-guides/run-vizro-ai.md), [how to create advanced charts](../user-guides/create-advanced-charts.md) and [how to add your Vizro-AI charts to a Vizro dashboard](../user-guides/add-generated-chart-usecase.md). You may also want to review the tutorial on [how to generate a Vizro dashboard with Vizro-AI](quickstart-dashboard.md)
+
+[linegraph]: ../../assets/tutorials/chart/GDP_Composition_Graph.png
diff --git a/vizro-ai/docs/pages/user-guides/add-generated-chart-usecase.md b/vizro-ai/docs/pages/user-guides/add-generated-chart-usecase.md
index 922fcb3b4..60eb24100 100644
--- a/vizro-ai/docs/pages/user-guides/add-generated-chart-usecase.md
+++ b/vizro-ai/docs/pages/user-guides/add-generated-chart-usecase.md
@@ -2,17 +2,15 @@
This guide explains the different ways in which you can add a chart generated by Vizro-AI to an existing [Vizro dashboard](https://github.com/mckinsey/vizro/tree/main/vizro-core).
-## Use Vizro-AI's generated code
+## Use Vizro-AI's generated code
1. Create a chart with Vizro-AI that you would like to visualize in a dashboard.
In this example, we aim to create a chart that illustrates the population development of each continent over time. To gain deeper insights and access the underlying code responsible for generating the chart, include `return_elements=True` in the `plot()` method. Let's execute the provided code and examine the outcome.
!!! example "Vizro-AI chart"
-
=== "Code for the cell"
-
- ```py
+ ```python
import vizro_ai
from vizro_ai import VizroAI
import vizro.plotly.express as px
@@ -23,23 +21,25 @@ This guide explains the different ways in which you can add a chart generated by
df = px.data.gapminder()
vizro_ai = VizroAI(model="gpt-4o")
- result = vizro_ai.plot(df,
- """Plot a bubble chart to show the changes in life expectancy
- and GDP per capita for each country over time.
- Color the bubbles by continent.
- Add animation on yearly basis, and do not use facets.
- Put the legend on top""", return_elements=True)
+ result = vizro_ai.plot(
+ df,
+ """Plot a bubble chart to show the changes in life expectancy
+ and GDP per capita for each country over time.
+ Color the bubbles by continent.
+ Add animation on yearly basis, and do not use facets.
+ Put the legend on top""",
+ return_elements=True,
+ )
- print(f"Insight:\n{result.chart_insights}\n" )
- print(f"Code explanation:\n{result.code_explanation}\n\nCode:\n{result.code_vizro}\n" )
+ print(f"Insight:\n{result.chart_insights}\n")
+ print(f"Code explanation:\n{result.code_explanation}\n\nCode:\n{result.code_vizro}\n")
result.get_fig_object(df).show()
```
- === "Result"
- [![VizroAIChart]][VizroAIChart]
- [VizroAIChart]: ../../assets/user_guides/vizro-ai-chart.png
+ === "Result"
+ [![VizroAIChart]][vizroaichart]
-2. Insert the resulting chart into a dashboard.
+1. Insert the resulting chart into a dashboard.
Once you are satisfied with the chart, you can add it to a [Vizro](https://github.com/mckinsey/vizro/tree/main/vizro-core) dashboard.
@@ -62,11 +62,9 @@ This guide explains the different ways in which you can add a chart generated by
return fig
```
-The `custom_chart` function is an example of the [custom chart](https://vizro.readthedocs.io/en/stable/pages/user-guides/custom-charts). It returns a `go.Figure()` object.
-This object must then be passed to the `figure` argument of the Vizro [Graph](https://vizro.readthedocs.io/en/stable/pages/user-guides/graph) model.
+The `custom_chart` function is an example of the [custom chart](https://vizro.readthedocs.io/en/stable/pages/user-guides/custom-charts). It returns a `go.Figure()` object. This object must then be passed to the `figure` argument of the Vizro [Graph](https://vizro.readthedocs.io/en/stable/pages/user-guides/graph) model.
!!! example "Vizro-AI chart within vizro dashboard"
-
=== "Code for the cell"
```py hl_lines="8-23 31"
from vizro import Vizro
@@ -100,35 +98,30 @@ This object must then be passed to the `figure` argument of the Vizro [Graph](ht
title = 'Demographics',
components = [
vm.Graph(figure=custom_chart(df)),
- vm.Graph(figure = px.box(df,
- x='continent',
- y='lifeExp',
- color='continent',
- title='Life Expectancy per Continent'))],
+ vm.Graph(
+ figure=px.box(
+ df, x='continent', y='lifeExp', color='continent', title='Life Expectancy per Continent'
+ )
+ )
+ ],
controls = [
vm.Filter(column='country'),
vm.Filter(column='continent')])
Vizro().build(vm.Dashboard(pages=[page])).run(port=8090)
```
- === "Result"
- [![VizroDashboard]][VizroDashboard]
-
- [VizroDashboard]: ../../assets/user_guides/chart_into_dashboard_large.png
+ === "Result"
+ [![VizroDashboard]][vizrodashboard]
## Use Vizro-AI dynamically to return a `fig` object
-We can also use Vizro-AI dynamically and assign the output of `plot()` directly to the fig variable, enabling its reuse in the `vm.Graph.figure` argument.
-This method offers streamlined efficiency, eliminating the need for code copying.
-Note that each dashboard run triggers an API call to the LLM, possibly escalating costs. This can be avoided if the `fig` object is stored and retrieved as needed, instead of making repeated calls to `plot()`.
+We can also use Vizro-AI dynamically and assign the output of `plot()` directly to the fig variable, enabling its reuse in the `vm.Graph.figure` argument. This method offers streamlined efficiency, eliminating the need for code copying. Note that each dashboard run triggers an API call to the LLM, possibly escalating costs. This can be avoided if the `fig` object is stored and retrieved as needed, instead of making repeated calls to `plot()`.
Executing the code below yields the identical dashboard as the example above.
-
!!! example "Use Vizro-AI fig directly in vizro dashboard"
=== "Code for the cell"
-
```py hl_lines="13-18 23"
from vizro import Vizro
import vizro.models as vm
@@ -143,28 +136,33 @@ Executing the code below yields the identical dashboard as the example above.
vizro_ai = VizroAI(model="gpt-4o")
fig = vizro_ai.plot(df,
- """Plot a bubble chart to show the changes in life expectancy
- and GDP per capita for each country over time.
- Color the bubbles by continent.
- Add animation on yearly basis, and do not use facets.
- Put the legend on top""")
+ """Plot a bubble chart to show the changes in life expectancy
+ and GDP per capita for each country over time.
+ Color the bubbles by continent.
+ Add animation on yearly basis, and do not use facets.
+ Put the legend on top"""
+ )
page = vm.Page(
title = 'Demographics',
components = [
vm.Graph(figure=fig),
- vm.Graph(figure = px.box(df,
- x='continent',
- y='lifeExp',
- color='continent',
- title='Life Expectancy per Continent'))],
+ vm.Graph(
+ figure=px.box(
+ df, x='continent', y='lifeExp', color='continent', title='Life Expectancy per Continent'
+ )
+ )
+ ],
controls = [
vm.Filter(column='country'),
vm.Filter(column='continent')])
Vizro().build(vm.Dashboard(pages=[page])).run(port=8090)
```
+
=== "Result"
- [![VizroDashboard2]][VizroDashboard2]
+ [![VizroDashboard2]][vizrodashboard2]
- [VizroDashboard2]: ../../assets/user_guides/chart_into_dashboard_large.png
+[vizroaichart]: ../../assets/user_guides/vizro-ai-chart.png
+[vizrodashboard]: ../../assets/user_guides/chart_into_dashboard_large.png
+[vizrodashboard2]: ../../assets/user_guides/chart_into_dashboard_large.png
diff --git a/vizro-ai/docs/pages/user-guides/advanced-options.md b/vizro-ai/docs/pages/user-guides/advanced-options.md
index 528a74912..4d63eaa35 100644
--- a/vizro-ai/docs/pages/user-guides/advanced-options.md
+++ b/vizro-ai/docs/pages/user-guides/advanced-options.md
@@ -4,19 +4,20 @@ This guide shows you how to use the advanced options of `VizroAI.plot`.
First we show how to change the input parameters of the function, as follows:
-* control over whether code gets executed,
-* the number of retries of `.plot` when it fails validation,
-* how to request a comprehensive output (when `return_elements=True`).
+- control over whether code gets executed,
+- the number of retries of `.plot` when it fails validation,
+- how to request a comprehensive output (when `return_elements=True`).
Second we show how to use this more comprehensive output, enabling control of code generation and `fig` object production.
## Inputs of `VizroAI.plot`
### `user_input`
-This is the natural language query from which, together with a data sample, the LLM creates a plotly chart. For the query, you can [use English or a different language](use-different-languages.md). The complexity of the resulting chart [depends on the vendor model capabilities](customize-vizro-ai.md#what-model-to-choose).
+This is the natural language query from which, together with a data sample, the LLM creates a plotly chart. For the query, you can [use English or a different language](use-different-languages.md). The complexity of the resulting chart [depends on the vendor model capabilities](customize-vizro-ai.md#what-model-to-choose).
### `df`
+
Supply any `pandas` data frame to base your query on. The LLM will receive a sample of this data frame to form an appropriate graph.
If the option `validate_code` is set to `True` (which it is by default), the LLM created chart code will be evaluated on a sample of this data frame.
@@ -24,10 +25,13 @@ If the option `validate_code` is set to `True` (which it is by default), the LLM
If `return_elements` is set to `False`, then the returned `fig` object will be created based on this (entire) data frame.
+
### `max_debug_retry`
+
This number determines how often the tool will try to correct an incorrect response (that fails various validation criteria). Under the hood this is [implemented via pydantic validators](https://docs.pydantic.dev/1.10/usage/validators/). The last response will be re-sent to the LLM together with the validation error(s) in order to receive an improved response. This concept is [inspired by the amazing instructor library](https://github.com/jxnl/instructor).
### `return_elements`
+
This boolean (by default `False`) determines the return type of `VizroAI.plot`.
If set to `False`, then dynamically generated Python code is executed to produce a `plotly.graph_objects.Figure` object from the LLM response and the user supplied data frame. Strictly speaking, it produces a `vizro.charts._charts_utils._DashboardReadyFigure`, which behaves essentially like the former, but is ready to be [inserted](add-generated-chart-usecase.md) into a [Vizro](https://vizro.readthedocs.io/en/stable/) dashboard. It also comes with the default Vizro dark theme.
@@ -35,8 +39,11 @@ If set to `False`, then dynamically generated Python code is executed to produce
If set to `True`, a class (pydantic model) is returned from which the `fig` object, but also various other outputs can be generated. (see below)
### `validate_code`
+
This boolean (by default `True`) determines whether the LLM generated Python code executes with a sample of the data in order to verify that it runs and produces a plotly figure. Be sure [to read and understand what it means when dynamically generated code is executed](../explanation/safety-in-vizro-ai.md#execution-of-dynamic-code-in-vizro-ai).
+
+
If `return_elements=True` **and** `validate_code=False`, then no code is executed to obtain the return of `VizroAI.plot`. This means that the code string obtained is not validated, but also that no code was executed.
## Output if `return_elements=True`
@@ -44,10 +51,10 @@ If `return_elements=True` **and** `validate_code=False`, then no code is execute
If `return_elements=True`, then instead of a `fig` object, a class is returned, which enables the following options:
### Obtain `vizro` code string
+
You can obtain the code string that would produce the answer to the user query as a Vizro dashboard ready figure as follows. The name for the function will be `custom_chart`:
!!! example "Vizro code"
-
=== "Code"
```py
from vizro_ai import VizroAI
@@ -76,10 +83,10 @@ You can obtain the code string that would produce the answer to the user query a
```
### Obtain `plotly` code string
+
You can obtain the code string that would produce the answer to the user query as a pure `plotly.graph_objects.Figure` as follows. The name for the function will be `custom_chart`:
!!! example "Plotly code"
-
=== "Code"
```py
from vizro_ai import VizroAI
@@ -110,10 +117,10 @@ You can obtain the code string that would produce the answer to the user query a
You can create the `fig` object using either of the above produced code strings (vizro or plotly), changing the chart name, and using different data. Note that when executing this function, the produced code string will be dynamically executed. Be sure [to read and understand what it means when dynamically generated code is executed](../explanation/safety-in-vizro-ai.md#execution-of-dynamic-code-in-vizro-ai).
#### Vizro ready
+
This `fig` object is in the standard `vizro_dark` theme, and can [be inserted into a Vizro dashboard](add-generated-chart-usecase.md).
!!! example "Vizro `fig` object"
-
=== "Code"
```py
from vizro_ai import VizroAI
@@ -128,15 +135,13 @@ This `fig` object is in the standard `vizro_dark` theme, and can [be inserted in
```
=== "Result"
- [![VizroAIChartVizro]][VizroAIChartVizro]
- ```
- [VizroAIChartVizro]: ../../assets/user_guides/VizroAIVizro.png
+ [![VizroAIChartVizro]][vizroaichartvizro]
#### Pure Plotly/Dash
+
This `fig` object is a basic plotly figure.
!!! example "Plotly `fig` object"
-
=== "Code"
```py
from vizro_ai import VizroAI
@@ -151,19 +156,18 @@ This `fig` object is a basic plotly figure.
```
=== "Result"
- [![VizroAIChartPlotly]][VizroAIChartPlotly]
- ```
- [VizroAIChartPlotly]: ../../assets/user_guides/VizroAIPlotly.png
+ [![VizroAIChartPlotly]][vizroaichartplotly]
#### Using different data
+
+
You can create the `fig` object with different data while ensuring the overall schema remains consistent. You can re-evaluate this function to generate various `fig` objects for different data. For example, the code could be generated using fake or sample data fed into Vizro-AI. When moving to production, you can switch the data source to the complete dataset, as long as the data schema is consistent.
+
!!! example "Different data"
-
=== "Code"
-
```py
from vizro_ai import VizroAI
import plotly.express as px
@@ -180,19 +184,14 @@ You can create the `fig` object with different data while ensuring the overall s
```
=== "Result"
- [![VizroAINewData]][VizroAINewData]
- ```
- [VizroAINewData]: ../../assets/user_guides/VizroAINewData.png
- ```
+ [![VizroAINewData]][vizroainewdata]
#### Changing the chart name
-This option executes the chart code with the name given under `chart_name`. This can be important when you want to avoid overwriting variables in the namespace.
+This option executes the chart code with the name given under `chart_name`. This can be important when you want to avoid overwriting variables in the namespace.
!!! example "Changing the `chart_name`"
-
=== "Code"
-
```py
from vizro_ai import VizroAI
import plotly.express as px
@@ -209,3 +208,7 @@ This option executes the chart code with the name given under `chart_name`. This
```py
```
+
+[vizroaichartplotly]: ../../assets/user_guides/VizroAIPlotly.png
+[vizroaichartvizro]: ../../assets/user_guides/VizroAIVizro.png
+[vizroainewdata]: ../../assets/user_guides/VizroAINewData.png
diff --git a/vizro-ai/docs/pages/user-guides/create-advanced-charts.md b/vizro-ai/docs/pages/user-guides/create-advanced-charts.md
index 15caa114e..4a8604511 100644
--- a/vizro-ai/docs/pages/user-guides/create-advanced-charts.md
+++ b/vizro-ai/docs/pages/user-guides/create-advanced-charts.md
@@ -1,4 +1,5 @@
# Advanced charts
+
This page explains how to use Vizro-AI to create charts with advanced visualizations and enhanced formatting.
## Animated map chart
@@ -6,7 +7,6 @@ This page explains how to use Vizro-AI to create charts with advanced visualizat
We'll create an animated map chart illustrating the GDP per capita of each continent over time. Run the code below and look at the result.
!!! example "Vizro-AI animated chart"
-
=== "Code"
```py
from vizro_ai import VizroAI
@@ -18,16 +18,13 @@ We'll create an animated map chart illustrating the GDP per capita of each conti
fig = vizro_ai.plot(df, "Visualize GDP per capita over the years for each country using map chart.")
fig.show()
```
- === "Result"
- [![AnimatedChart1]][AnimatedChart1]
- [AnimatedChart1]: ../../assets/tutorials/chart/advanced_chart_1.png
+ === "Result"
+ [![AnimatedChart1]][animatedchart1]
-Having unveiled our animated map chart showcasing GDP per capita development per country, it's clear that the map area is small, and it is difficult to differentiate countries.
-Next, we will try to tweak our prompt to improve the overall layout.
+Having unveiled our animated map chart showcasing GDP per capita development per country, it's clear that the map area is small, and it is difficult to differentiate countries. Next, we will try to tweak our prompt to improve the overall layout.
!!! example "Vizro-AI animated chart"
-
=== "Code"
```py
from vizro_ai import VizroAI
@@ -41,18 +38,15 @@ Next, we will try to tweak our prompt to improve the overall layout.
Show countries on the map. Increase the width and height of the figure.""")
fig.show()
```
- === "Result"
- [![AnimatedChart2]][AnimatedChart2]
-
- [AnimatedChart2]: ../../assets/tutorials/chart/advanced_chart_2.png
+ === "Result"
+ [![AnimatedChart2]][animatedchart2]
By incorporating the directive `Increase the width and height of the figure.` and `Show countries on the map.` we've successfully refined our animation.
Upon closer inspection, the title is too long and the color palette used does not match our needs. We can fix those issues with better and more specific prompting. Let's run the code below to visually improve the chart.
!!! example "Vizro-AI animated chart"
-
=== "Code"
```py
from vizro_ai import VizroAI
@@ -67,74 +61,14 @@ Upon closer inspection, the title is too long and the color palette used does no
Set title to be: `GDP per Capita over the years`. Use `Blues` as color sequence. """)
fig.show()
```
- === "Result"
- [![AnimatedChart3]][AnimatedChart3]
- [AnimatedChart3]: ../../assets/tutorials/chart/animated_advanced_chart.gif
+ === "Result"
+ [![AnimatedChart3]][animatedchart3]
Congratulations! You've now gained insights into harnessing the power of a LLM and Vizro-AI for crafting advanced charts and improving formatting. Don't forget, enabling `return_elements=True` in `.plot()` and check `chart_insights` and `code_explanation` is a good way of learning more about how a chart can be further improved and formatted.
-
Advanced charts are well-suited for [Vizro](https://github.com/mckinsey/vizro/tree/main/vizro-core) dashboard applications. You can create a chart using `vizro-ai` to plug into your `vizro` dashboard in seconds!
-
-## Polar bar chart
-
-A polar bar chart is a circular graph where each axis represents a different variable, typically used for displaying cyclical or directional data.
-It's suitable for comparing multiple variables across different categories or directions. Let's make one using Vizro-AI.
-
-
-!!! example "Polar Bar Chart"
-
- === "Resulting chart"
- [![VizroAIChart1]][VizroAIChart1]
-
- === "Code for the cell"
- ```py
- import vizro_ai
- from vizro_ai import VizroAI
- import plotly.express as px
-
- from dotenv import load_dotenv
- load_dotenv()
-
- df = px.data.wind()
-
- vizro_ai = VizroAI(model="gpt-4o")
- fig = vizro_ai.plot(df,
- """Describe wind frequency and direction using bar_polar chart.
- Increase the width and height of the figure.
- Improve layout by placing title to the left. Show legend""")
- fig.show()
- ```
-
- [VizroAIChart1]: ../../assets/user_guides/polar_bar_chart.png
-
-
-
-## 3D surface plot
-
-Let's explore how to generate a 3-dimensional surface plot with VizroAI.
-
-!!! example "Surface plot"
-
- === "Resulting chart"
- [![VizroAIChart3]][VizroAIChart3]
-
- === "Code for the cell"
- ```py
- import vizro_ai
- from vizro_ai import VizroAI
- import plotly.express as px
-
- from dotenv import load_dotenv
- load_dotenv()
-
- df = px.data.gapminder()
-
- vizro_ai = VizroAI(model="gpt-4o")
- fig = vizro_ai.plot(df, "create a surface plot")
- fig.show()
- ```
-
- [VizroAIChart3]: ../../assets/user_guides/surface_plot.gif
+[animatedchart1]: ../../assets/tutorials/chart/advanced_chart_1.png
+[animatedchart2]: ../../assets/tutorials/chart/advanced_chart_2.png
+[animatedchart3]: ../../assets/tutorials/chart/animated_advanced_chart.gif
diff --git a/vizro-ai/docs/pages/user-guides/create-complex-dashboard.md b/vizro-ai/docs/pages/user-guides/create-complex-dashboard.md
index eb2e07f38..fbec99025 100644
--- a/vizro-ai/docs/pages/user-guides/create-complex-dashboard.md
+++ b/vizro-ai/docs/pages/user-guides/create-complex-dashboard.md
@@ -9,6 +9,7 @@ The following example shows how to use Vizro-AI to generate a complex Vizro dash
If you haven't already installed Vizro-AI and set up the API key for OpenAI, follow the [installation guide](../user-guides/install.md).
## 1. Prepare the data
+
Next, prepare the data to pass to Vizro-AI. In this example, we use the [election data](https://plotly.com/python-api-reference/generated/plotly.express.data.html#plotly.express.data.election) and the [stocks data](https://plotly.com/python-api-reference/generated/plotly.express.data.html#plotly.express.data.stocks).
```py
@@ -18,7 +19,6 @@ df1 = px.data.election()
df2 = px.data.stocks(datetimes=True)
```
-
## 2. Prepare the user prompt
Devise a string of text to form the prompt that requests Vizro-AI to generate the Vizro dashboard.
@@ -104,9 +104,7 @@ dashboard = vizro_ai.dashboard([df1, df2], user_question)
The call to `dashboard()` triggers the dashboard building process. Once Vizro-AI finishes this process, you can launch the dashboard with `build()`.
!!! example "Generated dashboard"
-
- === "Code for the cell"
-
+ === "Code"
```py
import vizro_ai
from vizro_ai import VizroAI
@@ -177,10 +175,10 @@ The call to `dashboard()` triggers the dashboard building process. Once Vizro-AI
```
=== "Page1"
- [![VizroAIDashboardPage1]][VizroAIDashboardPage1]
+ [![VizroAIDashboardPage1]][vizroaidashboardpage1]
=== "Page2"
- [![VizroAIDashboardPage2]][VizroAIDashboardPage2]
+ [![VizroAIDashboardPage2]][vizroaidashboardpage2]
- [VizroAIDashboardPage1]: ../../assets/user_guides/dashboard/dashboard1_page1.png
- [VizroAIDashboardPage2]: ../../assets/user_guides/dashboard/dashboard1_page2.png
+[vizroaidashboardpage1]: ../../assets/user_guides/dashboard/dashboard1_page1.png
+[vizroaidashboardpage2]: ../../assets/user_guides/dashboard/dashboard1_page2.png
diff --git a/vizro-ai/docs/pages/user-guides/customize-vizro-ai.md b/vizro-ai/docs/pages/user-guides/customize-vizro-ai.md
index 3087d7f1a..03f35cbe5 100644
--- a/vizro-ai/docs/pages/user-guides/customize-vizro-ai.md
+++ b/vizro-ai/docs/pages/user-guides/customize-vizro-ai.md
@@ -3,8 +3,8 @@
This guide shows how to set up a large language model (LLM) for use with Vizro-AI. Setting up a LLM is required for the package to generate charts and dashboards based on natural language queries. To ensure responsible use, review the vendor’s guidelines on risk mitigation before using the model to understand potential model limitations and best practices.
## Supported models
-Vizro-AI supports **any** model that is available via [Langchain's `BaseChatModel` class](https://api.python.langchain.com/en/latest/language_models/langchain_core.language_models.chat_models.BaseChatModel.html#langchain_core.language_models.chat_models.BaseChatModel), and that has the [`with_structured_output` method](https://python.langchain.com/v0.2/docs/how_to/structured_output/#the-with_structured_output-method) implemented. An overview of the [most common vendor models supporting this functionality](https://python.langchain.com/v0.2/docs/integrations/chat/) can be found in Langchain's documentation. For ease of use one can also choose some models via a string parameter.
+Vizro-AI supports **any** model that is available via [Langchain's `BaseChatModel` class](https://api.python.langchain.com/en/latest/language_models/langchain_core.language_models.chat_models.BaseChatModel.html#langchain_core.language_models.chat_models.BaseChatModel), and that has the [`with_structured_output` method](https://python.langchain.com/v0.2/docs/how_to/structured_output/#the-with_structured_output-method) implemented. An overview of the [most common vendor models supporting this functionality](https://python.langchain.com/v0.2/docs/integrations/chat/) can be found in Langchain's documentation. For ease of use one can also choose some models via a string parameter.
### Setting model via string for ease of use
@@ -14,34 +14,30 @@ We have created shortcuts with sensible defaults (mainly setting `temperature=0`
vizro_ai = VizroAI(model="")
```
-!!!note
+!!! note
For the string settings to work, you must supply your API key via environment variables. The relevant variable names to be set are noted in each vendor tab.
=== "OpenAI"
+ | Environment variable | Name(s) |
+ | -------------------- | ----------------- |
+ | API key | `OPENAI_API_KEY` |
+ | Base API URL | `OPENAI_API_BASE` |
- | Env variable | Name(s) |
- | ----------- | ------------------------------------ |
- | API key | `OPENAI_API_KEY` |
- | Base API URL | `OPENAI_API_BASE` |
-
- To use OpenAI with Vizro-AI, you must have an account with paid-for credits available. None of the free accounts will suffice. [Check the OpenAI models and pricing on their website](https://platform.openai.com/docs/models). Before using a model, please review OpenAI's guidelines on risk mitigation to understand potential model limitations and best practices.
- [See the OpenAI site for more details on responsible usage](https://platform.openai.com/docs/guides/safety-best-practices).
+ To use OpenAI with Vizro-AI, you must have an account with paid-for credits available. None of the free accounts will suffice. [Check the OpenAI models and pricing on their website](https://platform.openai.com/docs/models). Before using a model, please review OpenAI's guidelines on risk mitigation to understand potential model limitations and best practices. [See the OpenAI site for more details on responsible usage](https://platform.openai.com/docs/guides/safety-best-practices).
- `gpt-4o-mini` **default**
- `gpt-4-turbo`
- `gpt-4o`
=== "Anthropic"
-
_Currently works only for `VizroAI.plot` - we are working on making it available for `VizroAI.dashboard`_
- | Env variable | Name(s) |
- | ----------- | ------------------------------------ |
- | API key | `ANTHROPIC_API_KEY` |
- | Base API URL | `ANTHROPIC_API_URL`,`ANTHROPIC_BASE_URL` |
+ | Environment variable | Name(s) |
+ | -------------------- | ---------------------------------------- |
+ | API key | `ANTHROPIC_API_KEY` |
+ | Base API URL | `ANTHROPIC_API_URL`,`ANTHROPIC_BASE_URL` |
- To use Anthropic with Vizro-AI, you must have an account with paid-for credits available. None of the free accounts will suffice. [Check the Anthropic models and pricing on their website](https://docs.anthropic.com/en/docs/about-claude/models). Before using a model, please review Anthropic guidelines on risk mitigation to understand potential model limitations and best practices.
- [See the Anthropic site for more details on responsible usage](https://support.anthropic.com/en/collections/4078535-trust-safety/).
+ To use Anthropic with Vizro-AI, you must have an account with paid-for credits available. None of the free accounts will suffice. [Check the Anthropic models and pricing on their website](https://docs.anthropic.com/en/docs/about-claude/models). Before using a model, please review Anthropic guidelines on risk mitigation to understand potential model limitations and best practices. [See the Anthropic site for more details on responsible usage](https://support.anthropic.com/en/collections/4078535-trust-safety/).
- `claude-3-5-sonnet-latest`
- `claude-3-opus-latest`
@@ -55,17 +51,14 @@ vizro_ai = VizroAI(model="")
```
=== "MistralAI"
+ _Currently works only for `VizroAI.plot` - we are working on making it available for `VizroAI.dashboard`_
- _Currently works only for `VizroAI.plot` - we are working on making it available for `VizroAI.dashboard`_
-
- | Env variable | Name(s) |
- | ----------- | ------------------------------------ |
- | API key | `MISTRAL_API_KEY` |
- | Base API URL | `MISTRAL_BASE_URL` |
+ | Environment variable | Name(s) |
+ | -------------------- | ------------------ |
+ | API key | `MISTRAL_API_KEY` |
+ | Base API URL | `MISTRAL_BASE_URL` |
- To use Mistral with Vizro-AI, you can either use their API, which comes with [an associated cost](https://mistral.ai/technology/#pricing), or you could use their models for free under the Apache 2.0 license. In that case you need to setup the model API yourself. You can check [all available Mistral models including pricing on their website](https://docs.mistral.ai/getting-started/models/models_overview). This will also explain which version the below string acronyms currently point to.
- Before usage, please review Mistral guidelines on risk mitigation to understand potential model limitations and best practices.
- [See the Mistral site for more details on responsible usage](https://help.mistral.ai/en/collections/272960-le-chat/).
+ To use Mistral with Vizro-AI, you can either use their API, which comes with [an associated cost](https://mistral.ai/technology/#pricing), or you could use their models for free under the Apache 2.0 license. In that case you need to setup the model API yourself. You can check [all available Mistral models including pricing on their website](https://docs.mistral.ai/getting-started/models/models_overview). This will also explain which version the below string acronyms currently point to. Before usage, please review Mistral guidelines on risk mitigation to understand potential model limitations and best practices. [See the Mistral site for more details on responsible usage](https://help.mistral.ai/en/collections/272960-le-chat/).
- `mistral-large-latest`
- `open-mistral-nemo`
@@ -79,18 +72,23 @@ vizro_ai = VizroAI(model="")
At the time of writing, we found that even the best Mistral models struggled to produce more than the simplest charts, but these outcomes can change drastically overtime.
-!!!note
+!!! note
When choosing the string representation, it sometimes can be tricky to have the correct environment variable set for the API key (and potential base URL). In case you cannot get this to work, we recommend instantiating the model directly (see below) and providing the API key via the models parameters.
+
### Setting model via class for additional configuration
+
+
Beyond passing a string, you can pass **any** model derived from [Langchain's `BaseChatModel` class](https://api.python.langchain.com/en/latest/language_models/langchain_core.language_models.chat_models.BaseChatModel.html#langchain_core.language_models.chat_models.BaseChatModel) that has the [`with_structured_output` method](https://python.langchain.com/v0.2/docs/how_to/structured_output/#the-with_structured_output-method) implemented. An overview of the [most common vendor models supporting this functionality](https://python.langchain.com/v0.2/docs/integrations/chat/) can be found in Langchain's documentation.
When choosing this approach, you can customize your model beyond the chosen default from the string instantiation. The choice of available arguments depends on the specific vendor implementation, but usually the main parameter to tweak is the temperature.
+
To ensure a deterministic answer to our queries, we've set the temperature to 0 in the string instantiation. If you prefer more creative (but potentially more unstable) responses, you can raise the temperature to a maximum of 1.
+
Below you can find an example where a custom model is instantiated with various custom parameters. Note that we manually set the API key and base URL, which is the easiest way to get it set up.
diff --git a/vizro-ai/docs/pages/user-guides/install.md b/vizro-ai/docs/pages/user-guides/install.md
index 3b6a6193d..8feda60d0 100644
--- a/vizro-ai/docs/pages/user-guides/install.md
+++ b/vizro-ai/docs/pages/user-guides/install.md
@@ -4,12 +4,11 @@ In this guide you'll learn how to set up the prerequisites needed for Vizro-AI,
Vizro-AI supports macOS, Linux, and Windows. It works with Python 3.9 and later. You can specify the version of Python to use with Vizro-AI when you set up a virtual environment.
-
## Set up a virtual environment
+
You should create a virtual environment for each Vizro-AI project you work on to isolate its Python dependencies from those of other projects. See the following references to learn more about [Python virtual environments](https://realpython.com/python-virtual-environments-a-primer/), [Conda virtual environments](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#starting-conda) or [watch an explainer video about them](https://youtu.be/YKfAwIItO7M).
??? information "How to create a virtual environment for your Vizro-AI project"
-
The simplest way to create a virtual environment in Python is `venv`, which is included in the Python standard library. Create a directory for your project and navigate to it. For example:
```bash
@@ -18,6 +17,7 @@ You should create a virtual environment for each Vizro-AI project you work on to
```
Next, create and activate a new virtual environment in this directory with `venv`:
+
```bash
python3 -m venv .venv
source .venv/bin/activate
@@ -62,8 +62,8 @@ You should see a return output of the form `x.y.z`.
Vizro-AI supports **any** model that is available via [Langchain's `BaseChatModel` class](https://api.python.langchain.com/en/latest/language_models/langchain_core.language_models.chat_models.BaseChatModel.html#langchain_core.language_models.chat_models.BaseChatModel), and that has the [`with_structured_output` method](https://python.langchain.com/v0.2/docs/how_to/structured_output/#the-with_structured_output-method) implemented. An overview of the [most common vendor models supporting this functionality](https://python.langchain.com/v0.2/docs/integrations/chat/) can be found in Langchain's documentation.
-
### Set up access to OpenAI (as an example for any vendor)
+
To use OpenAI with Vizro-AI you need an API key, which you can get by [creating an OpenAI account if you don't already have one](https://platform.openai.com/account/api-keys).
We recommend that you consult the [third-party API key section of the disclaimer documentation](../explanation/disclaimer.md).
@@ -72,8 +72,7 @@ There are two common ways to set up the API key in a development environment.
__Method 1: Set an environment variable for a single project__
-To make the API key available for a single project, you can create a local `.env`
-file to store it. Then, you can load the API key from that `.env` file in your development environment.
+To make the API key available for a single project, you can create a local `.env` file to store it. Then, you can load the API key from that `.env` file in your development environment.
The `.env` file should look as follows (containing your key rather than `abc123`):
@@ -86,8 +85,7 @@ By default, `vizro-ai` automatically loads the `.env` file, by searching the cur
If you would like to customize the `.env` file location and name, you can manually customize the search to override the default and specify the path and name of a custom `.env` file.
??? example "How to override the default location of the .`env` file:"
-
- ```py
+ ```python
from dotenv import load_dotenv, find_dotenv
from pathlib import Path
@@ -100,33 +98,26 @@ If you would like to customize the `.env` file location and name, you can manual
# Load the specified .env file
load_dotenv(env_file)
```
+
Refer to [Python-dotenv documentation](https://saurabh-kumar.com/python-dotenv/reference/) for further information.
!!! warning "Don't share your secret API key!"
-
You should avoid committing the `.env` file to version control. You can do this for Git by adding `.env` to your `.gitignore` file.
-
__Method 2: Set an environment variable for all projects__
-To make the OpenAI API key available for all projects, you can set it as a system environment
-variable. Refer to the section ["Set up your API key for all projects"](https://platform.openai.com/docs/quickstart/step-2-setup-your-api-key?context=python)
-in the OpenAI documentation. (It is under the dropdown of "Step 2: Set up your API key").
+To make the OpenAI API key available for all projects, you can set it as a system environment variable. Refer to the section ["Set up your API key for all projects"](https://platform.openai.com/docs/quickstart/step-2-setup-your-api-key?context=python) in the OpenAI documentation. (It is under the dropdown of "Step 2: Set up your API key").
-The documentation gives step-by-step instructions for setting up the API key as an environment
-variable, on operating systems including Windows and MacOS.
+The documentation gives step-by-step instructions for setting up the API key as an environment variable, on operating systems including Windows and MacOS.
-!!!note
+!!! note
Sometimes setting up the `.env` file can be fiddly. If necessary, you can supply the API key directly to the instantiated model. See [our user guide](./customize-vizro-ai.md#setting-model-via-class-for-additional-configuration) for this option. Remember not to commit this API key to any public space!
__Set the base URL (optional)__
You might need to give the base URL if you are using a custom OpenAI resource endpoint.
-The API base URL used for the OpenAI connector is set to `https://api.openai.com/v1` by default.
-If you are using a custom API endpoint, for example, if your organization has a designated API gateway,
-you can change the base URL by setting it as an environment variable.
-
+The API base URL used for the OpenAI connector is set to `https://api.openai.com/v1` by default. If you are using a custom API endpoint, for example, if your organization has a designated API gateway, you can change the base URL by setting it as an environment variable.
Follow the approach above in Method 2 to add the environment variable `OPENAI_API_BASE` for use by all projects.
diff --git a/vizro-ai/docs/pages/user-guides/run-vizro-ai-dashboard.md b/vizro-ai/docs/pages/user-guides/run-vizro-ai-dashboard.md
index 2a9e59b52..f9d5944c9 100644
--- a/vizro-ai/docs/pages/user-guides/run-vizro-ai-dashboard.md
+++ b/vizro-ai/docs/pages/user-guides/run-vizro-ai-dashboard.md
@@ -3,14 +3,12 @@
This guide offers insights into different ways of running `VizroAI.dashboard` to generate a Vizro dashboards from natural language prompts.
??? note "Note: API key"
-
Make sure you have followed the [LLM setup guide](../user-guides/install.md#set-up-access-to-a-large-language-model) and that your API key is set up in a `.env` file in the same folder as your Notebook file (`.ipynb`).
## Run Vizro-AI dashboard
!!! example "Generated dashboard"
-
- === "Code"
+ === "Prompt"
```py
import vizro.plotly.express as px
from vizro_ai import VizroAI
@@ -36,25 +34,23 @@ This guide offers insights into different ways of running `VizroAI.dashboard` to
```
=== "Result"
- [![VizroAIDashboardPage1]][VizroAIDashboardPage1]
-
-
- [VizroAIDashboardPage1]: ../../assets/user_guides/dashboard/dashboard2_page1.png
+ 
This triggers the dashboard building process. Once Vizro-AI finishes the dashboard generation process, you can now launch the dashboard.
## Retrieve the Python code of the dashboard
To illustrate the process, lets use the example above.
+
+
Like the `VizroAI.plot` method, in order to produce more comprehensive output we need to set `return_elements=True`. `return_elements` is a boolean (by default `False`) which determines the return type of `VizroAI.dashboard`.
- If set to `False` it produces a `Vizro` dashboard object.
- If set to `True`, it returns a class (a Pydantic model) containing both the dashboard object and the code string used to generate it.
!!! example "View dashboard code"
-
- === "Code"
+ === "Prompt"
```py
import vizro.plotly.express as px
from vizro_ai import VizroAI
@@ -79,7 +75,8 @@ Like the `VizroAI.plot` method, in order to produce more comprehensive output we
print(result.code)
```
- === "Result"
+
+ === "Resulting code"
```py
######## Module Imports ##########
from vizro import Vizro
@@ -124,9 +121,11 @@ Like the `VizroAI.plot` method, in order to produce more comprehensive output we
To use the above code, you will still need to add three simple steps:
- Import your data.
+
```py
data = pd.read_csv('data.csv') # Replace 'data.csv' with your filename or path to your data
```
+
- After importing your data, register it in the data manager by uncommenting the data manager instance and assigning the imported data to it. See the Vizro guide on [connecting dashboard to data](https://vizro.readthedocs.io/en/stable/pages/user-guides/data/#reference-by-name/).
```py
@@ -134,9 +133,11 @@ To use the above code, you will still need to add three simple steps:
```
- Launch the dashboard by adding the code below at the end of the file:
+
```py
Vizro().build(dashboard).run()
```
+
Detailed guidance is provided in [dashboard generation tutorial](https://vizro.readthedocs.io/projects/vizro-ai/en/latest/pages/tutorials/quickstart/).
## Available Vizro components
@@ -144,22 +145,22 @@ Detailed guidance is provided in [dashboard generation tutorial](https://vizro.r
The following list is a table of the Vizro components currently supported by Vizro-AI. This list is not exhaustive, and we are actively working on adding more features to Vizro-AI.
| Feature type | Feature | Availability |
-|----------------------|------------------------------------------------------------------------------------------------------------------------------------------|-------------|
-| **Components** | [Graph](https://vizro.readthedocs.io/en/stable/pages/user-guides/graph/) | ✔ |
-| | [AG Grid](https://vizro.readthedocs.io/en/stable/pages/user-guides/table/#ag-grid) | ✔ |
-| | [Card](https://vizro.readthedocs.io/en/stable/pages/user-guides/card-button/) | ✔ |
-| | [Button](https://vizro.readthedocs.io/en/stable/pages/user-guides/card-button/) | ✖ |
-| | [Tabs](https://vizro.readthedocs.io/en/stable/pages/user-guides/tabs/) | ✖ |
-| | [Containers](https://vizro.readthedocs.io/en/stable/pages/user-guides/container/) | ✖ |
-| **Controls** | [Filter](https://vizro.readthedocs.io/en/stable/pages/user-guides/filters/) | ✔ |
-| | [Parameter](https://vizro.readthedocs.io/en/stable/pages/user-guides/parameters/) | ✖ |
-| **Navigation** | [Default navigation](https://vizro.readthedocs.io/en/stable/pages/user-guides/navigation/#use-the-default-navigation) | ✔ |
-| | [Custom navigation](https://vizro.readthedocs.io/en/stable/pages/user-guides/navigation/#customize-the-navigation-bar) | ✖ |
-| **Layout** | [Layout](https://vizro.readthedocs.io/en/stable/pages/user-guides/layouts/) | ✔ |
-| **Dashboard header** | [Dashboard title](https://vizro.readthedocs.io/en/stable/pages/user-guides/dashboard/) | ✔ |
-| | [Logo](https://vizro.readthedocs.io/en/stable/pages/user-guides/dashboard/) | ✖ |
-| **Actions** | [Pre-defined actions](https://vizro.readthedocs.io/en/stable/pages/user-guides/actions/#pre-defined-actions/) | ✖ |
-| | [Filter interaction between charts](https://vizro.readthedocs.io/en/stable/pages/user-guides/actions/#filter-data-by-clicking-on-chart/) | ✖ |
-| | [Custom actions](https://vizro.readthedocs.io/en/stable/pages/user-guides/actions/#custom-actions/) | ✖ |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
+| **Components** | [Graph](https://vizro.readthedocs.io/en/stable/pages/user-guides/graph/) | ✔ |
+| | [AG Grid](https://vizro.readthedocs.io/en/stable/pages/user-guides/table/#ag-grid) | ✔ |
+| | [Card](https://vizro.readthedocs.io/en/stable/pages/user-guides/card-button/) | ✔ |
+| | [Button](https://vizro.readthedocs.io/en/stable/pages/user-guides/card-button/) | ✖ |
+| | [Tabs](https://vizro.readthedocs.io/en/stable/pages/user-guides/tabs/) | ✖ |
+| | [Containers](https://vizro.readthedocs.io/en/stable/pages/user-guides/container/) | ✖ |
+| **Controls** | [Filter](https://vizro.readthedocs.io/en/stable/pages/user-guides/filters/) | ✔ |
+| | [Parameter](https://vizro.readthedocs.io/en/stable/pages/user-guides/parameters/) | ✖ |
+| **Navigation** | [Default navigation](https://vizro.readthedocs.io/en/stable/pages/user-guides/navigation/#use-the-default-navigation) | ✔ |
+| | [Custom navigation](https://vizro.readthedocs.io/en/stable/pages/user-guides/navigation/#customize-the-navigation-bar) | ✖ |
+| **Layout** | [Layout](https://vizro.readthedocs.io/en/stable/pages/user-guides/layouts/) | ✔ |
+| **Dashboard header** | [Dashboard title](https://vizro.readthedocs.io/en/stable/pages/user-guides/dashboard/) | ✔ |
+| | [Logo](https://vizro.readthedocs.io/en/stable/pages/user-guides/dashboard/) | ✖ |
+| **Actions** | [Pre-defined actions](https://vizro.readthedocs.io/en/stable/pages/user-guides/actions/#pre-defined-actions/) | ✖ |
+| | [Filter interaction between charts](https://vizro.readthedocs.io/en/stable/pages/user-guides/actions/#filter-data-by-clicking-on-chart/) | ✖ |
+| | [Custom actions](https://vizro.readthedocs.io/en/stable/pages/user-guides/actions/#custom-actions/) | ✖ |
If a feature you need for your dashboard isn't currently supported by Vizro-AI you can retrieve the dashboard code and add it by hand before running the dashboard.
diff --git a/vizro-ai/docs/pages/user-guides/run-vizro-ai.md b/vizro-ai/docs/pages/user-guides/run-vizro-ai.md
index 192df9ea5..0c392dbed 100644
--- a/vizro-ai/docs/pages/user-guides/run-vizro-ai.md
+++ b/vizro-ai/docs/pages/user-guides/run-vizro-ai.md
@@ -2,19 +2,18 @@
This guide offers insights into different ways of running `VizroAI.plot` to generate Plotly charts. We cover how to use:
-* [a Jupyter Notebook](#jupyter-notebook)
-* [a Python script](#python-script)
-* [integration into an application](#application-integration)
+- [a Jupyter Notebook](#jupyter-notebook)
+- [a Python script](#python-script)
+- [integration into an application](#application-integration)
## Jupyter Notebook
+
To run Vizro-AI code in a Jupyter Notebook, create a new cell and execute the code below to render the described visualization as output.
??? note "Note: API key"
-
- Make sure you have followed the [LLM setup guide](../user-guides/install.md#set-up-access-to-a-large-language-model) and thatyour api key is set up in a `.env` file in the same folder as your Notebook file (`.ipynb`).
+ Make sure you have followed the [LLM setup guide](../user-guides/install.md#set-up-access-to-a-large-language-model) and that your api key is set up in a `.env` file in the same folder as your Notebook file (`.ipynb`).
!!! example "Ask Vizro-AI to generate a bar chart"
-
=== "Code for the cell"
```py
import vizro.plotly.express as px
@@ -25,18 +24,17 @@ To run Vizro-AI code in a Jupyter Notebook, create a new cell and execute the co
df = px.data.gapminder()
vizro_ai.plot(df, "visualize the life expectancy per continent and color each continent")
```
- === "Result"
- [![BarChart]][BarChart]
- [BarChart]: ../../assets/user_guides/bar_chart_gdp_per_continent.png
+ === "Result"
+ [![BarChart]][barchart]
Note that if you run this code, its appearance may not precisely resemble the one displayed, as it is generated by a generative AI and can vary.
## Python script
+
You can use Vizro-AI in any standard development environment by creating a `.py` file and executing the code, which displays the output in a browser window. As Vizro-AI returns the `fig` object, you need to append `fig.show()` to the response object.
??? note "Note: API key"
-
Make sure you have followed [LLM setup guide](../user-guides/install.md#set-up-access-to-a-large-language-model) and that your API key is set up in the environment where your `.py` script is running with command as below:
```bash
@@ -44,7 +42,6 @@ You can use Vizro-AI in any standard development environment by creating a `.py`
```
!!! example "Ask Vizro-AI to generate a line chart"
-
=== "example.py"
```py
import vizro.plotly.express as px
@@ -56,13 +53,13 @@ You can use Vizro-AI in any standard development environment by creating a `.py`
fig = vizro_ai.plot(df, "describe life expectancy per continent over time")
fig.show()
```
- === "Result"
- [![LineChart]][LineChart]
- [LineChart]: ../../assets/user_guides/line_chart_life_expect.png
+ === "Result"
+ [![LineChart]][linechart]
## Application integration
-You may prefer to integrate Vizro-AI into an application that offers a UI for users to input prompts. For that you can take the `fig` object from the `.plot` call, and use it elsewhere
-in any application (you might also want to process it further, for example, by serializing it or similar). It is also possible to obtain the code that would produce the object. For any advanced usage options, refer to
-[our advanced options guide](advanced-options.md).
+You may prefer to integrate Vizro-AI into an application that offers a UI for users to input prompts. For that you can take the `fig` object from the `.plot` call, and use it elsewhere in any application (you might also want to process it further, for example, by serializing it or similar). It is also possible to obtain the code that would produce the object. For any advanced usage options, refer to [our advanced options guide](advanced-options.md).
+
+[barchart]: ../../assets/user_guides/bar_chart_gdp_per_continent.png
+[linechart]: ../../assets/user_guides/line_chart_life_expect.png
diff --git a/vizro-ai/docs/pages/user-guides/use-different-languages.md b/vizro-ai/docs/pages/user-guides/use-different-languages.md
index ff797f1fc..7c222fa37 100644
--- a/vizro-ai/docs/pages/user-guides/use-different-languages.md
+++ b/vizro-ai/docs/pages/user-guides/use-different-languages.md
@@ -1,8 +1,8 @@
# Generate visualizations using different languages
+
Vizro-AI is versatile, supporting prompts and chart visualizations in languages other than English. In this guide you will explore this capability with two examples, starting with Chinese where we inquire about visualizing the GDP per capita over time.
!!! example "Vizro-AI Chinese"
-
=== "Code for the cell"
```py
from vizro_ai import VizroAI
@@ -14,15 +14,13 @@ Vizro-AI is versatile, supporting prompts and chart visualizations in languages
fig = vizro_ai.plot(df, "请画一个世界年均GDP的趋势图")
fig.show()
```
- === "Result"
- [![ChineseChart]][ChineseChart]
- [ChineseChart]: ../../assets/tutorials/chart/ChineseExample.png
+ === "Result"
+ [![ChineseChart]][chinesechart]
Subsequently, we'll switch to German and prompt the visualization of life expectancy in the United States over time, comparing it to the global life expectancy trend. For this example, we'll include `return_elements=True` to obtain comprehensive insights into both the data and the generated code.
!!! example "Vizro-AI German"
-
=== "Code for the cell"
```py
from vizro_ai import VizroAI
@@ -36,7 +34,9 @@ Subsequently, we'll switch to German and prompt the visualization of life expect
print(f"Code:\n{result.code_explanation}\n{result.code_vizro}\n" )
result.get_fig_object(df).show()
```
+
=== "Result"
- [![GermanChart]][GermanChart]
+ [![GermanChart]][germanchart]
- [GermanChart]: ../../assets/tutorials/chart/GermanExample.png
+[chinesechart]: ../../assets/tutorials/chart/ChineseExample.png
+[germanchart]: ../../assets/tutorials/chart/GermanExample.png
diff --git a/vizro-ai/docs/pages/user-guides/vizro-ai-langchain-guide.md b/vizro-ai/docs/pages/user-guides/vizro-ai-langchain-guide.md
index 210f36410..b43653356 100644
--- a/vizro-ai/docs/pages/user-guides/vizro-ai-langchain-guide.md
+++ b/vizro-ai/docs/pages/user-guides/vizro-ai-langchain-guide.md
@@ -3,9 +3,9 @@
You can use Vizro-AI's functionality within a larger LangChain application. This guide shows how to integrate Vizro-AI's chart and dashboard generation capabilities as LangChain tools. Here are the steps you need to take:
1. [Set up the environment](#1-set-up-the-environment)
-2. [Define LangChain tools](#2-define-langchain-tools)
-3. [Set up the tool chain](#3-set-up-the-tool-chain)
-4. [Use the chain](#4-use-the-chain)
+1. [Define LangChain tools](#2-define-langchain-tools)
+1. [Set up the tool chain](#3-set-up-the-tool-chain)
+1. [Use the chain](#4-use-the-chain)
## 1. Set up the environment
@@ -51,6 +51,7 @@ def get_plot_code(df: Annotated[Any, InjectedToolArg], question: str) -> str:
)
return plot_elements.code_vizro
+
@tool(parse_docstring=True)
def get_dashboard_code(dfs: Annotated[Any, InjectedToolArg], question: str) -> str:
"""Generate the dashboard code.
@@ -80,6 +81,7 @@ Create a chain that handles tool execution and data injection:
tools = [get_plot_code, get_dashboard_code]
llm_with_tools = llm.bind_tools(tools)
+
# Create data injection chain
@chain
def inject_df(ai_msg):
@@ -95,13 +97,16 @@ def inject_df(ai_msg):
tool_calls.append(tool_call_copy)
return tool_calls
+
# Create tool router
tool_map = {tool.name: tool for tool in tools}
+
@chain
def tool_router(tool_call):
return tool_map[tool_call["name"]]
+
# Combine chains
chain = llm_with_tools | inject_df | tool_router.map()
```
@@ -111,26 +116,25 @@ chain = llm_with_tools | inject_df | tool_router.map()
Now you can use the chain to generate charts or dashboards based on natural language queries. The chain will generate code that you can use to create visualizations.
!!! example "Generate chart code"
-
=== "Code"
- ```py
+ ```python
# Load sample data
df = px.data.gapminder()
plot_response = chain.invoke("Plot GDP per capita for each continent")
print(plot_response[0].content)
```
+
=== "Vizro-AI Generated Code"
- ```py
+ ```python
import plotly.graph_objects as go
from vizro.models.types import capture
+
@capture("graph")
def custom_chart(data_frame):
continent_gdp = data_frame.groupby("continent")["gdpPercap"].mean().reset_index()
- fig = go.Figure(
- data=[go.Bar(x=continent_gdp["continent"], y=continent_gdp["gdpPercap"])]
- )
+ fig = go.Figure(data=[go.Bar(x=continent_gdp["continent"], y=continent_gdp["gdpPercap"])])
fig.update_layout(
title="GDP per Capita by Continent",
xaxis_title="Continent",
@@ -140,16 +144,18 @@ Now you can use the chain to generate charts or dashboards based on natural lang
```
!!! example "Generate dashboard code"
-
=== "Code"
- ```py
+ ```python
dfs = [px.data.gapminder()]
- dashboard_response = chain.invoke("Create a dashboard. This dashboard has a chart showing the correlation between gdpPercap and lifeExp.")
+ dashboard_response = chain.invoke(
+ "Create a dashboard. This dashboard has a chart showing the correlation between gdpPercap and lifeExp."
+ )
print(dashboard_response[0].content)
```
+
=== "Vizro-AI Generated Code"
- ```py
+ ```python
############ Imports ##############
import vizro.models as vm
from vizro.models.types import capture
@@ -160,9 +166,7 @@ Now you can use the chain to generate charts or dashboards based on natural lang
@capture("graph")
def gdp_life_exp_graph(data_frame):
fig = go.Figure()
- fig.add_trace(
- go.Scatter(x=data_frame["gdpPercap"], y=data_frame["lifeExp"], mode="markers")
- )
+ fig.add_trace(go.Scatter(x=data_frame["gdpPercap"], y=data_frame["lifeExp"], mode="markers"))
fig.update_layout(
title="GDP per Capita vs Life Expectancy",
xaxis_title="GDP per Capita",
diff --git a/vizro-core/CHANGELOG.md b/vizro-core/CHANGELOG.md
index 5f308c9d0..ef31d9d93 100644
--- a/vizro-core/CHANGELOG.md
+++ b/vizro-core/CHANGELOG.md
@@ -31,8 +31,7 @@ See the fragment files in the [changelog.d directory](https://github.com/mckinse
## Removed
-- Removed all CSS variables from `variables.css` and `token_names.css`, replacing them with CSS variables from `vizro-bootstrap.min.css`.
- Refer to [`vizro-bootstrap.min.css](https://github.com/mckinsey/vizro/blob/main/vizro-core/src/vizro/static/css/vizro-bootstrap.min.css) for the updated CSS variables. ([#886](https://github.com/mckinsey/vizro/pull/886))
+- Removed all CSS variables from `variables.css` and `token_names.css`, replacing them with CSS variables from `vizro-bootstrap.min.css`. Refer to [`vizro-bootstrap.min.css`](https://github.com/mckinsey/vizro/blob/main/vizro-core/src/vizro/static/css/vizro-bootstrap.min.css) for the updated CSS variables. ([#886](https://github.com/mckinsey/vizro/pull/886))
## Added
@@ -318,10 +317,7 @@ See the fragment files in the [changelog.d directory](https://github.com/mckinse
### Highlights ✨
-- Introduce `AgGrid` as a new `Page` component, allowing the usage of
- [AG Grid](https://www.ag-grid.com/) in
- `Vizro`. See the [user guide on tables](https://vizro.readthedocs.io/en/stable/pages/user_guides/table/)
- for more information. ([#289](https://github.com/mckinsey/vizro/pull/289),[#268](https://github.com/mckinsey/vizro/pull/268),[#324](https://github.com/mckinsey/vizro/pull/324))
+- Introduce `AgGrid` as a new `Page` component, allowing the usage of [AG Grid](https://www.ag-grid.com/) in `Vizro`. See the [user guide on tables](https://vizro.readthedocs.io/en/stable/pages/user_guides/table/) for more information. ([#289](https://github.com/mckinsey/vizro/pull/289),[#268](https://github.com/mckinsey/vizro/pull/268),[#324](https://github.com/mckinsey/vizro/pull/324))
## Changed
@@ -566,10 +562,10 @@ See the fragment files in the [changelog.d directory](https://github.com/mckinse
- Optimize the client-server communication ([#34](https://github.com/mckinsey/vizro/pull/34))
- - Eliminate most server side callbacks in favor of client-side callbacks
- - Add tests for client-side callbacks written in Node.js framework called `jest`.
- - Add hatch command `hatch run test-js` that runs unit tests written in `jest`.
- - Logging information now only displayed for action function carried out (no trigger or finished information)
+ - Eliminate most server side callbacks in favor of client-side callbacks
+ - Add tests for client-side callbacks written in Node.js framework called `jest`.
+ - Add hatch command `hatch run test-js` that runs unit tests written in `jest`.
+ - Logging information now only displayed for action function carried out (no trigger or finished information)
- Replaced all screenshots in the docs to reflect new navigation designs ([#48](https://github.com/mckinsey/vizro/pull/48))
@@ -613,21 +609,21 @@ See the fragment files in the [changelog.d directory](https://github.com/mckinse
- Add the following pydantic models:
- - Action
- - Button
- - Card
- - Checklist
- - Dashboard
- - Dropdown
- - Filter
- - Graph
- - Layout
- - Navigation
- - Page
- - Parameter
- - RadioItems
- - RangeSlider
- - Slider
- - VizroBaseModel
+ - Action
+ - Button
+ - Card
+ - Checklist
+ - Dashboard
+ - Dropdown
+ - Filter
+ - Graph
+ - Layout
+ - Navigation
+ - Page
+ - Parameter
+ - RadioItems
+ - RangeSlider
+ - Slider
+ - VizroBaseModel
- Enable the addition and usage of custom components and custom charts
diff --git a/vizro-core/README.md b/vizro-core/README.md
index 3a0cb5bc6..283717094 100644
--- a/vizro-core/README.md
+++ b/vizro-core/README.md
@@ -11,19 +11,13 @@
@@ -138,8 +130,7 @@ We encourage you to ask and answer technical questions via the [GitHub Issues](h
## Contributing
-To learn more about making a contribution,
-please see the [contributing guide](https://vizro.readthedocs.io/en/stable/pages/development/contributing/) for more information
+To learn more about making a contribution, please see the [contributing guide](https://vizro.readthedocs.io/en/stable/pages/development/contributing/) for more information
You can also view current and former [contributors](https://vizro.readthedocs.io/en/stable/pages/development/authors/)
diff --git a/vizro-core/changelog.d/20241202_150655_huong_li_nguyen_refactor_bs_example.md b/vizro-core/changelog.d/20241202_150655_huong_li_nguyen_refactor_bs_example.md
index 7c0d58d4f..4abc0f11e 100644
--- a/vizro-core/changelog.d/20241202_150655_huong_li_nguyen_refactor_bs_example.md
+++ b/vizro-core/changelog.d/20241202_150655_huong_li_nguyen_refactor_bs_example.md
@@ -10,36 +10,42 @@ Uncomment the section that is right (remove the HTML comment wrapper).
- 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))
-->
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/vizro-core/changelog.d/20241203_145221_antony.milne_mdformat.md b/vizro-core/changelog.d/20241203_145221_antony.milne_mdformat.md
new file mode 100644
index 000000000..4abc0f11e
--- /dev/null
+++ b/vizro-core/changelog.d/20241203_145221_antony.milne_mdformat.md
@@ -0,0 +1,54 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/vizro-core/changelog.d/20241203_150134_antony.milne_mdformat.md b/vizro-core/changelog.d/20241203_150134_antony.milne_mdformat.md
new file mode 100644
index 000000000..4abc0f11e
--- /dev/null
+++ b/vizro-core/changelog.d/20241203_150134_antony.milne_mdformat.md
@@ -0,0 +1,54 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/vizro-core/docs/index.md b/vizro-core/docs/index.md
index 1cc99a4ce..e9886376b 100644
--- a/vizro-core/docs/index.md
+++ b/vizro-core/docs/index.md
@@ -4,58 +4,56 @@ Vizro is a toolkit for creating modular data visualization applications.
less than 30 lines of configuration can create dashboards with multiple charts and filters
- - **Beautiful** - inbuilt visual design best practices are applied automatically,
- so users can create beautiful dashboards without needing to know any HTML, CSS or design principles.
+ - **Beautiful** - inbuilt visual design best practices are applied automatically, so users can create beautiful dashboards without needing to know any HTML, CSS or design principles.
- **Powerful** - advanced functionality and interactions come out-of-the-box, by using just a few lines of simple configuration.
- - **Quick and easy** - the simple configuration follows an intuitive "grammar of dashboards" which is quick to learn and easy to use.
- This removes most of the "glue code" that would otherwise need to be written. Thousands of lines of code are reduced to tens of lines of configuration.
- Users can configure Vizro dashboards without needing to know any advanced software development principles of how to build front-end applications.
+ - **Quick and easy** - the simple configuration follows an intuitive "grammar of dashboards" which is quick to learn and easy to use. This removes most of the "glue code" that would otherwise need to be written. Thousands of lines of code are reduced to tens of lines of configuration. Users can configure Vizro dashboards without needing to know any advanced software development principles of how to build front-end applications.
### You can extend and customize infinitely
Users benefit from the power of the Dash framework and the flexibility of React.
??? details "See more details"
-
- - **Dash** - since Vizro is built on top of Dash, then users benefit from all the underlying power and customizations offered by the Dash framework,
- including the ability to use extension libraries related to Dash.
+ - **Dash** - since Vizro is built on top of Dash, then users benefit from all the underlying power and customizations offered by the Dash framework, including the ability to use extension libraries related to Dash.
- **React** - since Dash enables JavaScript React components to be incorporated into Dash applications, Vizro users can create custom charts and UI components which offer the infinite flexibility of React.
- **Vizro extensions** - adding extensions such as user defined custom charts, components, actions and data connectors is intuitively incorporated into the configuration language of Vizro.
@@ -83,74 +71,54 @@ Users benefit from the power of the Dash framework and the flexibility of React.
Consistency and re-usability designed for scale.
??? details "See more details"
-
- - **Prototype rapidly** - even complex dashboards can be created within minutes using Vizro,
- which enables prototype dashboards to be created and iterated on quickly and easily, with very low barrier to entry.
+ - **Prototype rapidly** - even complex dashboards can be created within minutes using Vizro, which enables prototype dashboards to be created and iterated on quickly and easily, with very low barrier to entry.
- **Deploy easily** - since Vizro is built on Dash which uses Flask, it is simple to deploy Vizro like any other Dash application, and use application servers such as Gunicorn to scale to multiple users.
- - **Scale** - since Vizro offers standardization of visual design, application architecture and configuration language,
- it is easier to scale across multiple developers, projects and implementations in a consistent and reusable way.
+ - **Scale** - since Vizro offers standardization of visual design, application architecture and configuration language, it is easier to scale across multiple developers, projects and implementations in a consistent and reusable way.
## How does Vizro differ from Dash or Streamlit?
-Potential users sometimes request comparisons between Vizro and similar tools such as Dash and Streamlit.
-In many ways a direct comparison is not possible as these products tackle somewhat different use cases and their relative pros and cons change depending on the particular requirements of each different user.
+Potential users sometimes request comparisons between Vizro and similar tools such as Dash and Streamlit. In many ways a direct comparison is not possible as these products tackle somewhat different use cases and their relative pros and cons change depending on the particular requirements of each different user.
Any attempt at a high-level explanation must rely on an oversimplification that misses many important nuances. With the caveat that it's not possible to "compare apples with pears", and that any comparison will have a different conclusion for different users, an oversimplified view could be:
??? details "Streamlit is great for rapid prototyping"
-
- - **rapid prototyping** - Streamlit's architecture allows you to write apps the same way you write plain Python scripts.
- To unlock this, Streamlit apps have a unique data flow: any time something must be updated on the screen, Streamlit reruns your entire Python script from top to bottom. [[1]](https://docs.streamlit.io/library/get-started/main-concepts)
- This turns data scripts into sharable web apps in minutes. [[2]](https://streamlit.io/)
- Adding a widget is the same as declaring a variable.
- (No need to write a backend, define routes, handle HTTP requests, connect a frontend, write HTML, CSS, JavaScript, etc. [[3]](https://streamlit.io/))
+ - **rapid prototyping** - Streamlit's architecture allows you to write apps the same way you write plain Python scripts. To unlock this, Streamlit apps have a unique data flow: any time something must be updated on the screen, Streamlit reruns your entire Python script from top to bottom. [\[1\]](https://docs.streamlit.io/library/get-started/main-concepts) This turns data scripts into sharable web apps in minutes. [\[2\]](https://streamlit.io/) Adding a widget is the same as declaring a variable. (No need to write a backend, define routes, handle HTTP requests, connect a frontend, write HTML, CSS, JavaScript, etc. [\[3\]](https://streamlit.io/))
??? details "Dash is great for customization and scalability"
-
- - **customization** - one of the great things about Dash is that it is built on top of React.js, a JavaScript library for building web components.
- Thousands of components have been built and released with open source licenses by the React community, any of which could be adapted into a Dash component. [[4]](https://dash.plotly.com/plugins)
- Dash supports adding custom CSS [[5]](https://dash.plotly.com/external-resources) and HTML, callbacks for custom behavior,
- and many component libraries such as Dash Bootstrap components [[6]](https://dash-bootstrap-components.opensource.faculty.ai/)
- - **scalability** - based on Flask which is widely adopted by the Python community and deployed in production environments
- everywhere [[7]](https://medium.com/plotly/introducing-dash-5ecf7191b503) Dash was designed to be a stateless framework. Stateless frameworks are more scalable and robust [[8]](https://dash.plotly.com/sharing-data-between-callbacks#why-share-state?)
+ - **customization** - one of the great things about Dash is that it is built on top of React.js, a JavaScript library for building web components. Thousands of components have been built and released with open source licenses by the React community, any of which could be adapted into a Dash component. [\[4\]](https://dash.plotly.com/plugins) Dash supports adding custom CSS [\[5\]](https://dash.plotly.com/external-resources) and HTML, callbacks for custom behavior, and many component libraries such as Dash Bootstrap components [\[6\]](https://dash-bootstrap-components.opensource.faculty.ai/)
+ - **scalability** - based on Flask which is widely adopted by the Python community and deployed in production environments everywhere [\[7\]](https://medium.com/plotly/introducing-dash-5ecf7191b503) Dash was designed to be a stateless framework. Stateless frameworks are more scalable and robust [\[8\]](https://dash.plotly.com/sharing-data-between-callbacks#why-share-state?)
??? details "Vizro is great for combining rapid prototyping with customization and scalability"
-
- **rapid prototyping** - since Vizro is a high-level framework providing declarative configuration, it is quick and easy to create powerful interactive apps in minutes, without needing to write callbacks, HTML, CSS, or JavaScript. Key topics such as applying state management, application architecture, and testing are done automatically by Vizro.
- **customization and scalability** - since Vizro is built on top of Dash, then users benefit from all the underlying power of the Dash framework for customization and scalability
- **beauty and robustness** - since Vizro uses inbuilt visual design and software development best practices, it automatically generates dashboards which look beautiful and can go from prototype to production quickly and easily
-All are great entry points to the world of data apps.
-If you prefer a top-down scripting style, then Streamlit is a powerful approach.
-If you prefer full control and customization over callbacks and layouts, then Dash is a powerful approach.
-If you prefer a configuration approach with in-built best practices, and the potential for customization and scalability through Dash, then Vizro is a powerful approach.
+All are great entry points to the world of data apps. If you prefer a top-down scripting style, then Streamlit is a powerful approach. If you prefer full control and customization over callbacks and layouts, then Dash is a powerful approach. If you prefer a configuration approach with in-built best practices, and the potential for customization and scalability through Dash, then Vizro is a powerful approach.
-For a more detailed comparison, it may help to visit the introductory articles of [Dash](https://medium.com/plotly/introducing-dash-5ecf7191b503), [Streamlit](https://towardsdatascience.com/coding-ml-tools-like-you-code-ml-models-ddba3357eace) and [Vizro](https://quantumblack.medium.com/introducing-vizro-a-toolkit-for-creating-modular-data-visualization-applications-3a42f2bec4db),
-to see how each tool serves a distinct purpose, and could be the best tool of choice.
+For a more detailed comparison, it may help to visit the introductory articles of [Dash](https://medium.com/plotly/introducing-dash-5ecf7191b503), [Streamlit](https://towardsdatascience.com/coding-ml-tools-like-you-code-ml-models-ddba3357eace) and [Vizro](https://quantumblack.medium.com/introducing-vizro-a-toolkit-for-creating-modular-data-visualization-applications-3a42f2bec4db), to see how each tool serves a distinct purpose, and could be the best tool of choice.
## How does Vizro compare with Python packages and business intelligence (BI) tools?
+
There are a number of Python packages and BI tools which offer support for visualization applications (such as Streamlit, Plotly/Dash, Tableau and PowerBI).
Vizro is intended to support several niches between the benefits from those tools, rather than being in direct comparison with any single tool. Therefore, direct comparisons are often only partially suitable, given the many features offered across this landscape.
-However, in general, there are several areas of functionality where Vizro can be particularly useful, such as in providing a simple configuration to speed up the assembly of components, leveraging inbuilt visual design, application architecture, and coding standards,
-along with the ability to scale easily across multiple developers and implementations.
+However, in general, there are several areas of functionality where Vizro can be particularly useful, such as in providing a simple configuration to speed up the assembly of components, leveraging inbuilt visual design, application architecture, and coding standards, along with the ability to scale easily across multiple developers and implementations.
??? details "See more details"
-
- | Functionality | Benefits | In context of Python packages | In context of BI tools |
- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
- | **Assembly system**
Vizro primarily offers configuration to simplify that assembly of components offered by existing packages (currently leveraging Plotly/Dash), and so occupies a slightly different niche from libraries offering primarily the lower-level components themselves. It also removes the requirement from users to implement certain code standards for the assembled code themselves, and therefore saves time on often time consuming things such as writing unit tests and ensuring linting coverage. | Many BI tools incorporate the assembly of higher-level concepts automatically from GUI (drop-and-drag) interfaces, and occupy a slightly different niche to the configuration driven assembly offered by Vizro. | - | **Inbuilt visual design decisions**
Vizro applies that to a wide range of component combinations and complex user flows, offering a holistic and comprehensive approach to automatically enable beautiful visual design best practices, whilst allowing customization and flexibility. | Many BI tools supply inbuilt color choices and visual design choices for certain components.
Vizro offers inbuilt visual design for components in addition to the ability to customize them in a flexible way where needed (for example through CSS), and automatic arrangement of components on the screen. | - | **Inbuilt application architecture decisions**
Vizro applies that to a wide range of component combinations and complex user flows, offering a holistic and comprehensive approach to the entire application architecture, whilst allowing customization and flexibility where relevant. | Many BI tools apply proprietary application architecture by default.
Vizro enables the user to view and understand the application architecture by directly viewing the code. | - | **Declarative configuration, in multiple formats**
Vizro simplifies this approach, and facilitates the extension of the assembly system to enable integration with other tools such as Kedro to programmatically and dynamically generate the relevant dashboard configurations in a streamlined way. | Many BI tools solely use a GUI and/or drag-and-drop interface for defining dashboards, and leverage proprietary configuration formats.
Vizro enables the user to view and understand the configuration by viewing it directly, in addition to being able to edit it directly. | - | **Mostly tech agnostic “grammar of dashboards”**
Vizro offers a “grammar of dashboards” with declaration which is largely tech agnostic and can be extended to non-Python languages. | Many BI tools utilize an implicit internal “grammar of dashboards” which is specific to the proprietary language(s) on with which they are built.
Vizro offers an explicit configuration grammar and allows users to leverage a mostly tech agnostic approach (which can be extended in future). | - | **Inbuilt validation**
Vizro offers the advantages of Pydantic based models for many elements of the configuration process, which leverages the validation and guidance inherent in that process to facilitate implementation by users. | Many BI tools have inbuilt guideline systems to ensure components are combined in a valid way, and give feedback to the manual user to help guide through that process.
Vizro utilizes a flexible system which can be extended to give feedback to programmatic generation of configuration. | - | **Modularity**
Vizro supports modularity of groups of components (such as their implementation together as a dashboard screen), which can be easily transferred between implementations as configuration. | Many BI tools supply extensions and plugins which support modularity of visualizations.
Vizro supports modularity of groups of components (such as their implementation together as a dashboard screen), which can be easily transferred between implementations as configuration. | - | **Flexibility**
Vizro supports a holistic combination of low-code and high-code approaches which support less technical and more technical users individually while allowing them much flexibility in implementation according to their technical level. | Many BI tools offer a no-code (or at least low-code) approach to creating charts and dashboards, along with varying forms of plugins to increase flexibility.
Vizro unlocks Python custom functions to be able to power this user driven flexibility in a technically advanced way, with a high degree of control and visibility over the code, whilst also supporting less technical users through low-code configuration. | - | **Scaling**
Vizro makes it easy to scale by replicating the relatively small amount of configuration in 1 file between usages, rather than replicating a large amount of code across many files between usages.
Updating configuration programmatically from a central location is often easier than updating code. When sharing between users, it can be easier to inherit and understand configuration than the underlying code. The visual consistency makes it easier to scale within or between projects while maintaining visual coherence. | Many BI tools allow scaling through GUI drag-and-drop interfaces (having some functionality for duplication or propagating changes) for single users.
Vizro makes it easy to leverage tools such as Git to enable almost any number of users to collaborate effectively, therefore allowing the number of developers on a single project to scale easily.
Since updates can be propagated programmatically easily from a central location, it allows scaling across almost any number of related implementations which can be kept up to date and aligned without the need to manually adjust each implementation when updates are required. | - | **Python first**
Vizro is no different in this respect. By leveraging Plotly/Dash, Vizro is also able to benefit from the power and flexibility offered by JavaScript via React, whilst still presenting a format that is Python first to the user (by making use of the ability offered by Dash to effectively wrap those components into Python). | Many BI tools do not offer direct or full integration with Python.
Vizro supports a Python first approach which leverages the power and flexibility of Python, and the open source community supporting that wide ranging functionality. | - | **Open source**
Vizro is no different in this respect. | Many BI tools follow a license fee model and/or charge for ongoing development and maintenance.
Vizro requires no license fee, and offers ongoing development and support, which helps to remove some barriers to usage. | + | Functionality | Benefits | In context of Python packages | In context of BI tools | + | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | **Assembly system**
Vizro primarily offers configuration to simplify that assembly of components offered by existing packages (currently leveraging Plotly/Dash), and so occupies a slightly different niche from libraries offering primarily the lower-level components themselves. It also removes the requirement from users to implement certain code standards for the assembled code themselves, and therefore saves time on often time consuming things such as writing unit tests and ensuring linting coverage. | Many BI tools incorporate the assembly of higher-level concepts automatically from GUI (drop-and-drag) interfaces, and occupy a slightly different niche to the configuration driven assembly offered by Vizro. | + | **Inbuilt visual design decisions**
Vizro applies that to a wide range of component combinations and complex user flows, offering a holistic and comprehensive approach to automatically enable beautiful visual design best practices, whilst allowing customization and flexibility. | Many BI tools supply inbuilt color choices and visual design choices for certain components.
Vizro offers inbuilt visual design for components in addition to the ability to customize them in a flexible way where needed (for example through CSS), and automatic arrangement of components on the screen. | + | **Inbuilt application architecture decisions**
Vizro applies that to a wide range of component combinations and complex user flows, offering a holistic and comprehensive approach to the entire application architecture, whilst allowing customization and flexibility where relevant. | Many BI tools apply proprietary application architecture by default.
Vizro enables the user to view and understand the application architecture by directly viewing the code. | + | **Declarative configuration, in multiple formats**
Vizro simplifies this approach, and facilitates the extension of the assembly system to enable integration with other tools such as Kedro to programmatically and dynamically generate the relevant dashboard configurations in a streamlined way. | Many BI tools solely use a GUI and/or drag-and-drop interface for defining dashboards, and leverage proprietary configuration formats.
Vizro enables the user to view and understand the configuration by viewing it directly, in addition to being able to edit it directly. | + | **Mostly tech agnostic “grammar of dashboards”**
Vizro offers a “grammar of dashboards” with declaration which is largely tech agnostic and can be extended to non-Python languages. | Many BI tools utilize an implicit internal “grammar of dashboards” which is specific to the proprietary language(s) on with which they are built.
Vizro offers an explicit configuration grammar and allows users to leverage a mostly tech agnostic approach (which can be extended in future). | + | **Inbuilt validation**
Vizro offers the advantages of Pydantic based models for many elements of the configuration process, which leverages the validation and guidance inherent in that process to facilitate implementation by users. | Many BI tools have inbuilt guideline systems to ensure components are combined in a valid way, and give feedback to the manual user to help guide through that process.
Vizro utilizes a flexible system which can be extended to give feedback to programmatic generation of configuration. | + | **Modularity**
Vizro supports modularity of groups of components (such as their implementation together as a dashboard screen), which can be easily transferred between implementations as configuration. | Many BI tools supply extensions and plugins which support modularity of visualizations.
Vizro supports modularity of groups of components (such as their implementation together as a dashboard screen), which can be easily transferred between implementations as configuration. | + | **Flexibility**
Vizro supports a holistic combination of low-code and high-code approaches which support less technical and more technical users individually while allowing them much flexibility in implementation according to their technical level. | Many BI tools offer a no-code (or at least low-code) approach to creating charts and dashboards, along with varying forms of plugins to increase flexibility.
Vizro unlocks Python custom functions to be able to power this user driven flexibility in a technically advanced way, with a high degree of control and visibility over the code, whilst also supporting less technical users through low-code configuration. | + | **Scaling**
Vizro makes it easy to scale by replicating the relatively small amount of configuration in 1 file between usages, rather than replicating a large amount of code across many files between usages.
Updating configuration programmatically from a central location is often easier than updating code. When sharing between users, it can be easier to inherit and understand configuration than the underlying code. The visual consistency makes it easier to scale within or between projects while maintaining visual coherence. | Many BI tools allow scaling through GUI drag-and-drop interfaces (having some functionality for duplication or propagating changes) for single users.
Vizro makes it easy to leverage tools such as Git to enable almost any number of users to collaborate effectively, therefore allowing the number of developers on a single project to scale easily.
Since updates can be propagated programmatically easily from a central location, it allows scaling across almost any number of related implementations which can be kept up to date and aligned without the need to manually adjust each implementation when updates are required. | + | **Python first**
Vizro is no different in this respect. By leveraging Plotly/Dash, Vizro is also able to benefit from the power and flexibility offered by JavaScript via React, whilst still presenting a format that is Python first to the user (by making use of the ability offered by Dash to effectively wrap those components into Python). | Many BI tools do not offer direct or full integration with Python.
Vizro supports a Python first approach which leverages the power and flexibility of Python, and the open source community supporting that wide ranging functionality. | + | **Open source**
Vizro is no different in this respect. | Many BI tools follow a license fee model and/or charge for ongoing development and maintenance.
Vizro requires no license fee, and offers ongoing development and support, which helps to remove some barriers to usage. | ## When would an alternative to Vizro be more suitable? @@ -162,18 +130,14 @@ There are a number of cases where alternatives to Vizro may be more suitable, in - where Python developers are already very comfortable leveraging other Python packages - - ## How can I report a bug? Head over to our [GitHub issues](https://github.com/mckinsey/vizro/issues) and [create a new bug report](https://github.com/mckinsey/vizro/issues/new/choose). We will try to reproduce the bug you've reported and follow up with the next steps. - ## How can I request a feature? To raise a feature request, head to our [GitHub issues](https://github.com/mckinsey/vizro/issues) and [create a new feature request](https://github.com/mckinsey/vizro/issues/new/choose). The team will then try to understand the request in more detail, explore the feasibility and prioritize it in relation to the current roadmap. We will get back to you as soon as possible with an estimate of whether and when this feature could be released. - ## I still have a question. Where can I ask it? We are happy to receive general questions around Vizro. Take a look at our [GitHub issues](https://github.com/mckinsey/vizro/issues) and [create a new issue](https://github.com/mckinsey/vizro/issues/new/choose) by clicking "General question". diff --git a/vizro-core/docs/pages/explanation/your-examples.md b/vizro-core/docs/pages/explanation/your-examples.md index 6f1da044a..91a0baa2b 100644 --- a/vizro-core/docs/pages/explanation/your-examples.md +++ b/vizro-core/docs/pages/explanation/your-examples.md @@ -4,37 +4,43 @@ This page lists videos, blog posts, and examples of Vizro usage in repositories If you have something you'd like us to include on the list, or spot something that we should include, let us know: -* you can [raise an issue](https://github.com/mckinsey/vizro/issues) on the Vizro repository, -* better still, you can [make a PR to contribute](../explanation/contributing.md) to this page. - +- you can [raise an issue](https://github.com/mckinsey/vizro/issues) on the Vizro repository, +- better still, you can [make a PR to contribute](../explanation/contributing.md) to this page. !!! note - The Vizro team and QuantumBlack, AI by McKinsey, do not take responsibility for third party content. In curating the list below, we may inspect or test an example at time of inclusion, but cannot guarantee the content thereafter. ## Videos -* From [Charming Data on YouTube](https://www.youtube.com/@CharmingData): - * [Build Python Data Apps with Vizro Dash](https://www.youtube.com/watch?v=wmQ6_GZ0zSk). - * [Introduction to Vizro Actions - Plotly Dash](https://www.youtube.com/watch?v=bom-9275Cic&t=8s). - * [Use Dash AG Grid within a Vizro app](https://www.youtube.com/watch?v=YvtVcXwQw0E). - * [Visual Vocabulary Dashboard showcasing charting options in Vizro and Plotly](https://www.youtube.com/watch?v=OZNAokBKT-M). +- From [Charming Data on YouTube](https://www.youtube.com/@CharmingData): + - [Build Python Data Apps with Vizro Dash](https://www.youtube.com/watch?v=wmQ6_GZ0zSk). + - [Introduction to Vizro Actions - Plotly Dash](https://www.youtube.com/watch?v=bom-9275Cic&t=8s). + - [Use Dash AG Grid within a Vizro app](https://www.youtube.com/watch?v=YvtVcXwQw0E). + - [Visual Vocabulary Dashboard showcasing charting options in Vizro and Plotly](https://www.youtube.com/watch?v=OZNAokBKT-M). ## Blog posts -* [Introducing Vizro](https://quantumblack.medium.com/introducing-vizro-a-toolkit-for-creating-modular-data-visualization-applications-3a42f2bec4db). -* [Creating Custom Dashboards with Vizro: A Comprehensive Guide](https://medium.com/@saffand03/creating-custom-dashboards-with-vizro-a-comprehensive-guide-73c69c6f851e). + +- [Introducing Vizro](https://quantumblack.medium.com/introducing-vizro-a-toolkit-for-creating-modular-data-visualization-applications-3a42f2bec4db). +- [Creating Custom Dashboards with Vizro: A Comprehensive Guide](https://medium.com/@saffand03/creating-custom-dashboards-with-vizro-a-comprehensive-guide-73c69c6f851e). + -* [I built a reusable dashboard read-the-docs traffic analytics using vizro](https://medium.com/towards-data-science/i-built-a-reusable-dashboard-for-read-the-docs-traffic-analytics-using-vizro-47dc15dc04f8). + +- [I built a reusable dashboard read-the-docs traffic analytics using vizro](https://medium.com/towards-data-science/i-built-a-reusable-dashboard-for-read-the-docs-traffic-analytics-using-vizro-47dc15dc04f8). + -* [Visualizing data science insights](https://medium.com/quantumblack/visualizing-data-science-insights-dfc8ad0646b6). + +- [Visualizing data science insights](https://medium.com/quantumblack/visualizing-data-science-insights-dfc8ad0646b6). + -* [A low-code, attractive, sharable data dashboard: Illustrating my LinkedIn connections in 100 lines of Python](https://medium.com/design-bootcamp/a-low-code-attractive-sharable-data-dashboard-a60badba2a03). + +- [A low-code, attractive, sharable data dashboard: Illustrating my LinkedIn connections in 100 lines of Python](https://medium.com/design-bootcamp/a-low-code-attractive-sharable-data-dashboard-a60badba2a03). ## Examples on GitHub or PyCafe -* [Personal Vizro app demos by Vizro team member `huong-li-nguyen`](https://github.com/huong-li-nguyen/vizro-app-demos). -* [Proof of concept example by `viiviandias`](https://github.com/viiviandias/poc-vizro/blob/main/brasil_stocks.ipynb). -* [Amazon sales analysis by `Bottleneck44`](https://github.com/Bottleneck44/Amazon-Sales-Analysis/blob/main/Amazon-analysis.ipynb). -* [Insight-AI: Chart and business insight generation by `micky091` using vizro-ai](https://github.com/micky0919/insight-ai) -* [Music trend analysis using Vizro](https://py.cafe/app/KhushaliP/vizro-music-trend-analysis) by [`KhushaliP`](https://github.com/KhushaliP) +- [Personal Vizro app demos by Vizro team member `huong-li-nguyen`](https://github.com/huong-li-nguyen/vizro-app-demos). +- [Proof of concept example by `viiviandias`](https://github.com/viiviandias/poc-vizro/blob/main/brasil_stocks.ipynb). +- [Amazon sales analysis by `Bottleneck44`](https://github.com/Bottleneck44/Amazon-Sales-Analysis/blob/main/Amazon-analysis.ipynb). +- [Insight-AI: Chart and business insight generation by `micky091` using vizro-ai](https://github.com/micky0919/insight-ai) +- [Music trend analysis using Vizro](https://py.cafe/app/KhushaliP/vizro-music-trend-analysis) by [`KhushaliP`](https://github.com/KhushaliP) + diff --git a/vizro-core/docs/pages/tutorials/explore-components.md b/vizro-core/docs/pages/tutorials/explore-components.md index 52a0ef3e3..a770dacf1 100644 --- a/vizro-core/docs/pages/tutorials/explore-components.md +++ b/vizro-core/docs/pages/tutorials/explore-components.md @@ -23,12 +23,10 @@ Vizro uses [`Graph`][vizro.models.Graph] objects and [Plotly Express functions]( The code below shows the steps necessary to add a box plot to the page: 1. Add a Vizro [`Graph`][vizro.models.Graph] to the `components` list. -2. Add a [`plotly.express.box`](https://plotly.com/python-api-reference/generated/plotly.express.box.html#plotly.express.box) figure to the list of components. - +1. Add a [`plotly.express.box`](https://plotly.com/python-api-reference/generated/plotly.express.box.html#plotly.express.box) figure to the list of components. !!! example "First component" === "app.py" - ```{.python pycafe-link} from vizro import Vizro import vizro.models as vm @@ -55,23 +53,19 @@ The code below shows the steps necessary to add a box plot to the page: ``` === "Result" - - [![FirstPage1]][FirstPage1] - - [FirstPage1]: ../../assets/tutorials/dashboard/dashboard21.png - + [![FirstPage1]][firstpage1] ??? note "To run the dashboard in a Notebook or script" - Paste the above code into a Notebook cell, run the Notebook, and evaluate it. --- + If you prefer to use Python scripts to Notebooks, here's how to try out the dashboard: 1. Create a new script called `app.py`. - 2. Copy the code above into the script. - 3. Navigate to the directory where `app.py` file is located using your terminal. - 4. Run the script by executing the command `python app.py`. + 1. Copy the code above into the script. + 1. Navigate to the directory where `app.py` file is located using your terminal. + 1. Run the script by executing the command `python app.py`. Once the script is running, open your web browser and go to `localhost:8050`. You should see the dashboard page with the gapminder data displayed, as shown in the `Result` tab above. @@ -83,11 +77,10 @@ You can combine and arrange various types of `components` on a dashboard page. T The code below adds two components to the page: -* A [`Card`][vizro.models.Card] to insert markdown text into the dashboard. -* A [`Graph`][vizro.models.Graph] to illustrate GDP development per continent since 1952 as a line graph. +- A [`Card`][vizro.models.Card] to insert markdown text into the dashboard. +- A [`Graph`][vizro.models.Graph] to illustrate GDP development per continent since 1952 as a line graph. !!! warning "Before you run this code in a Jupyter Notebook" - If you are following this tutorial in a Jupyter Notebook, you need to restart the kernel each time you evaluate the code. If you do not, you will see error messages such as "Components must uniquely map..." because those components already exist from the previous evaluation. !!! example "Add components" @@ -103,6 +96,7 @@ The code below adds two components to the page: ) ``` + === "Code second component" ```py @@ -113,8 +107,8 @@ The code below adds two components to the page: "gdpPercap":"GDP Per Cap"}, title=''), ) ``` - === "app.py" + === "app.py" ```{.python pycafe-link} from vizro import Vizro import vizro.models as vm @@ -152,15 +146,13 @@ The code below adds two components to the page: dashboard = vm.Dashboard(pages=[first_page]) Vizro().build(dashboard).run() ``` - === "Result" - [![FirstPage2]][FirstPage2] - [FirstPage2]: ../../assets/tutorials/dashboard/dashboard22.png + === "Result" + [![FirstPage2]][firstpage2] As you explore the dashboard, you may notice that the current layout could be further enhanced. The charts appear cramped, while the text component has ample unused space. The next section explains how to configure the layout and arrange the components. !!! note "An introduction to Vizro-AI" - In the example above, the code to create the line graph was generated using [Vizro-AI](https://vizro.readthedocs.io/en/latest/pages/tutorials/first-dashboard/). Vizro-AI enables you to use English, or other languages, to create interactive charts with [Plotly](https://plotly.com/python/) by simplifying the process through use of a large language model. In essence, Vizro-AI generates code from natural language instructions so that you can add it into a Vizro dashboard, such as in the example above. Find out more in the [Vizro-AI documentation](https://vizro.readthedocs.io/projects/vizro-ai/)! @@ -169,32 +161,23 @@ As you explore the dashboard, you may notice that the current layout could be fu By default, Vizro places each element in the order it was added to `components` list, and spaces them equally. -You can use the [`Layout`][vizro.models.Layout] object to specify the placement and size of components on the page. To learn more about how to -configure layouts, check out [How to use layouts](../user-guides/layouts.md). +You can use the [`Layout`][vizro.models.Layout] object to specify the placement and size of components on the page. To learn more about how to configure layouts, check out [How to use layouts](../user-guides/layouts.md). -The following layout configuration positions the text at the top and the two charts side -by side, giving them more space relative to the text component: +The following layout configuration positions the text at the top and the two charts side by side, giving them more space relative to the text component: ```python -grid=[ [0, 0], - [1, 2], - [1, 2], - [1, 2] ] +grid = [[0, 0], [1, 2], [1, 2], [1, 2]] ``` -Vizro interprets these values as follows. First, the configuration divides the available space into two columns and -four rows. Each element in the list (such as `[0,0]`) represents one row of the grid layout: +Vizro interprets these values as follows. First, the configuration divides the available space into two columns and four rows. Each element in the list (such as `[0,0]`) represents one row of the grid layout:  -Each element in the `components` list is referenced with a unique number, and placed on the grid as visualized with the white frames. The `Card`, is referenced by 0 as it is the first element in the `components` list. It is placed in the first row and spans across both -columns (`[0, 0]`). The two `Graph` objects, referenced by 1 and 2, are positioned next to each other and occupy a column each. +Each element in the `components` list is referenced with a unique number, and placed on the grid as visualized with the white frames. The `Card`, is referenced by 0 as it is the first element in the `components` list. It is placed in the first row and spans across both columns (`[0, 0]`). The two `Graph` objects, referenced by 1 and 2, are positioned next to each other and occupy a column each.  -The `Graph` objects occupy three rows, denoted by `[1, 2], [1, 2], [1, 2]`, while the -`Card` only occupies one row `[0, 0]`. As a result, the `Graph` objects occupy three-quarters of the vertical space, while the -`Card` occupies one-quarter of it. +The `Graph` objects occupy three rows, denoted by `[1, 2], [1, 2], [1, 2]`, while the `Card` only occupies one row `[0, 0]`. As a result, the `Graph` objects occupy three-quarters of the vertical space, while the `Card` occupies one-quarter of it.  @@ -205,8 +188,8 @@ Run the code below to apply the layout to the dashboard page: ```py layout=vm.Layout(grid=[[0, 0], [1, 2], [1, 2], [1, 2]]) ``` - === "app.py" + === "app.py" ```{.python pycafe-link} from vizro import Vizro import vizro.models as vm @@ -244,32 +227,24 @@ Run the code below to apply the layout to the dashboard page: dashboard = vm.Dashboard(pages=[first_page]) Vizro().build(dashboard).run() ``` - === "Result" - [![FirstPage3]][FirstPage3] - - [FirstPage3]: ../../assets/tutorials/dashboard/dashboard23.png + === "Result" + [![FirstPage3]][firstpage3] ### 2.4. Add a control for dashboard interactivity -Controls add interactivity to the dashboard page and make it more dynamic, enabling users -to have greater control and customization over the displayed data and components. +Controls add interactivity to the dashboard page and make it more dynamic, enabling users to have greater control and customization over the displayed data and components. There are two types of control: -* [`Filters`][vizro.models.Filter] enable users to filter a column of the underlying data. -* [`Parameters`][vizro.models.Parameter] enable users to change arguments or properties of the components, such as adjusting colors. - +- [`Filters`][vizro.models.Filter] enable users to filter a column of the underlying data. +- [`Parameters`][vizro.models.Parameter] enable users to change arguments or properties of the components, such as adjusting colors. The guides on [`How to use Filters`](../user-guides/filters.md) and [`How to use Parameters`](../user-guides/parameters.md) offer instructions on their application. For further customization, refer to the guide on [`How to use selectors`](../user-guides/selectors.md). To link a control to a component, use an `id` assigned to the component, which is unique across all dashboard pages and serves as a reference to target it. -To illustrate, let's add a [`Filter`][vizro.models.Filter] on specific -continents of the underlying gapminder data. The [`Filter`][vizro.models.Filter] requires the `column` argument, that denotes -the target column to be filtered. Each `control` also has a `targets` parameter, to specify the -data and components targeted by the `control`. For this dashboard, both charts -are listed in the `targets` parameter, meaning that the filter is be applied to both charts. However, you can apply the [`Filter`][vizro.models.Filter] to only one specific chart if required. +To illustrate, let's add a [`Filter`][vizro.models.Filter] on specific continents of the underlying gapminder data. The [`Filter`][vizro.models.Filter] requires the `column` argument, that denotes the target column to be filtered. Each `control` also has a `targets` parameter, to specify the data and components targeted by the `control`. For this dashboard, both charts are listed in the `targets` parameter, meaning that the filter is be applied to both charts. However, you can apply the [`Filter`][vizro.models.Filter] to only one specific chart if required. !!! example "Configure filter" === "Code" @@ -278,8 +253,8 @@ are listed in the `targets` parameter, meaning that the filter is be applied to vm.Filter(column="continent", targets=["box_cont", "line_gdp"]), ] ``` - === "app.py" + === "app.py" ```{.python pycafe-link} from vizro import Vizro import vizro.models as vm @@ -324,16 +299,14 @@ are listed in the `targets` parameter, meaning that the filter is be applied to ``` === "Result" - [![FirstPage4]][FirstPage4] - - [FirstPage4]: ../../assets/tutorials/dashboard/dashboard24.png + [![FirstPage4]][firstpage4] Fantastic job! You have completed first dashboard page and gained valuable skills to: 1. [Create an initial figure on a dashboard page](#2-create-a-first-dashboard-page) -2. [Add extra components](#22-add-further-components) -3. [Arrange them in a layout configuration](#23-configure-the-layout) -4. [Set up an interactive dashboard control](#24-add-a-control-for-dashboard-interactivity). +1. [Add extra components](#22-add-further-components) +1. [Arrange them in a layout configuration](#23-configure-the-layout) +1. [Set up an interactive dashboard control](#24-add-a-control-for-dashboard-interactivity). ## 3. Create a second dashboard page @@ -343,16 +316,10 @@ Every [`Page`][vizro.models.Page] that you want to display needs to be added to In creating a [`Parameter`][vizro.models.Parameter] object, you define the `target` it applies to. In the code below: -* The first parameter enables the user to change the color mapping for the `virginica` category of the iris data, targeting both charts. -* The second parameter adjusts the opacity of the first chart alone, through `scatter_iris.opacity`. - +- The first parameter enables the user to change the color mapping for the `virginica` category of the iris data, targeting both charts. +- The second parameter adjusts the opacity of the first chart alone, through `scatter_iris.opacity`. -In general, `targets` for [`Parameters`][vizro.models.Parameter] are set following the structure of -`component_id.argument`. In certain cases, you may see a nested structure for the `targets`. An example of this is -`scatter_iris.color_discrete_map.virginica`. A nested structure targets a specific attribute within a -component. In this particular example, it specifies that only the color of the virginica flower type should be changed. -More information on how to set `targets` for [`Parameters`][vizro.models.Parameter] can be found in the [how-to guide -for parameters](../user-guides/parameters.md). +In general, `targets` for [`Parameters`][vizro.models.Parameter] are set following the structure of `component_id.argument`. In certain cases, you may see a nested structure for the `targets`. An example of this is `scatter_iris.color_discrete_map.virginica`. A nested structure targets a specific attribute within a component. In this particular example, it specifies that only the color of the virginica flower type should be changed. More information on how to set `targets` for [`Parameters`][vizro.models.Parameter] can be found in the [how-to guide for parameters](../user-guides/parameters.md). !!! example "Second page" === "Code" @@ -392,8 +359,8 @@ for parameters](../user-guides/parameters.md). ], ) ``` - === "app.py" + === "app.py" ```{.python pycafe-link} from vizro import Vizro import vizro.models as vm @@ -470,25 +437,19 @@ for parameters](../user-guides/parameters.md). dashboard = vm.Dashboard(pages=[first_page,second_page]) Vizro().build(dashboard).run() ``` - === "Result" - [![SecondPage]][SecondPage] - [SecondPage]: ../../assets/tutorials/dashboard/dashboard3.png + === "Result" + [![SecondPage]][secondpage] ### 3.1. Customize with selectors -The code in the example above uses two different types of [`selector`](../user-guides/selectors.md) objects, namely -[`Dropdown`][vizro.models.Dropdown] and [`Slider`][vizro.models.Slider] upon the -[`Parameters`][vizro.models.Parameter]. The `selectors` enable configuration of the controls to customize their behavior and appearance. +The code in the example above uses two different types of [`selector`](../user-guides/selectors.md) objects, namely [`Dropdown`][vizro.models.Dropdown] and [`Slider`][vizro.models.Slider] upon the [`Parameters`][vizro.models.Parameter]. The `selectors` enable configuration of the controls to customize their behavior and appearance. -The first parameter is a [`Dropdown`][vizro.models.Dropdown]. It is configured with two available -options, disables multi-selection, and has a default `value` set to blue. Users can choose a single option -from the dropdown. +The first parameter is a [`Dropdown`][vizro.models.Dropdown]. It is configured with two available options, disables multi-selection, and has a default `value` set to blue. Users can choose a single option from the dropdown. The second parameter is a [`Slider`][vizro.models.Slider] with a default value of 0.8. Users can adjust a value within the specified range of `min=0` and `max=1`. -You can apply selectors to configure [`Filters`][vizro.models.Filter] and -[`Parameters`][vizro.models.Parameter] to fine-tune the behavior and appearance of the controls. The selectors currently available are as follows: +You can apply selectors to configure [`Filters`][vizro.models.Filter] and [`Parameters`][vizro.models.Parameter] to fine-tune the behavior and appearance of the controls. The selectors currently available are as follows: - [`Parameter`][vizro.models.Parameter]: - [`Checklist`][vizro.models.Checklist] @@ -499,24 +460,17 @@ You can apply selectors to configure [`Filters`][vizro.models.Filter] and ## 4. The final touches -This section puts everything together by adding a -homepage to the example for navigation between the two separate pages. +This section puts everything together by adding a homepage to the example for navigation between the two separate pages. -For easy navigation within your dashboard, we'll create a page that serves as the entry point for the user. -On this homepage are two [`Cards`][vizro.models.Card] which serve as tiles that can be customized with a title, some text, and an -image. These cards link to the subpages within your dashboard using their `href` attributes as `href="/first-page"` and `href="/second-page"`. This -establishes the navigation links from the homepage to each of the subpages. +For easy navigation within your dashboard, we'll create a page that serves as the entry point for the user. On this homepage are two [`Cards`][vizro.models.Card] which serve as tiles that can be customized with a title, some text, and an image. These cards link to the subpages within your dashboard using their `href` attributes as `href="/first-page"` and `href="/second-page"`. This establishes the navigation links from the homepage to each of the subpages. -Each page is added to the dashboard using the following line of code: -`vm.Dashboard(pages=[home_page, first_page, second_page])`. This ensures that all the pages are accessible. +Each page is added to the dashboard using the following line of code: `vm.Dashboard(pages=[home_page, first_page, second_page])`. This ensures that all the pages are accessible. -The code below illustrates a functional dashboard where you can navigate from the homepage to each -of the subpages. Additionally, you can use the navigation panel on the left side to switch between the three pages. +The code below illustrates a functional dashboard where you can navigate from the homepage to each of the subpages. Additionally, you can use the navigation panel on the left side to switch between the three pages. !!! example "Final dashboard" - === "Code" - ```py + ```python home_page = vm.Page( title="Homepage", components=[ @@ -542,12 +496,13 @@ of the subpages. Additionally, you can use the navigation panel on the left side ), ], ) - ``` - ```py + + ... + dashboard = vm.Dashboard(pages=[home_page, first_page, second_page]) ``` - === "app.py" + === "app.py" ```{.python pycafe-link} from vizro import Vizro @@ -651,31 +606,23 @@ of the subpages. Additionally, you can use the navigation panel on the left side dashboard = vm.Dashboard(pages=[home_page, first_page, second_page]) Vizro().build(dashboard).run() ``` - === "Homepage" - [![FinalPage]][FinalPage] - [FinalPage]: ../../assets/tutorials/dashboard/dashboard4.png + === "Homepage" + [![FinalPage]][finalpage] === "Subpage1" - [![FinalPage1]][FinalPage1] - - [FinalPage1]: ../../assets/tutorials/dashboard/dashboard2.png + [![FinalPage1]][finalpage1] === "Subpage2" - [![FinalPage2]][FinalPage2] + [![FinalPage2]][finalpage2] - [FinalPage2]: ../../assets/tutorials/dashboard/dashboard3.png - -Congratulations on completing this tutorial! You have acquired the knowledge to configure layouts, add components, and -implement interactivity in Vizro dashboards, working across two navigable pages. +Congratulations on completing this tutorial! You have acquired the knowledge to configure layouts, add components, and implement interactivity in Vizro dashboards, working across two navigable pages. ## Find out more After completing the tutorial you now have a solid understanding of the main elements of Vizro and how to bring them together to create dynamic and interactive data visualizations. -You can find out more about the Vizro by reading the [components overview page](../user-guides/components.md). To gain more in-depth knowledge about the usage and configuration details of individual controls, check out the guides dedicated to [Filters](../user-guides/filters.md), [Parameters](../user-guides/parameters.md) -and [Selectors](../user-guides/selectors.md). If you'd like to understand more about different ways to configure the navigation of your dashboard, head -to [Navigation](../user-guides/navigation.md). +You can find out more about the Vizro by reading the [components overview page](../user-guides/components.md). To gain more in-depth knowledge about the usage and configuration details of individual controls, check out the guides dedicated to [Filters](../user-guides/filters.md), [Parameters](../user-guides/parameters.md), and [Selectors](../user-guides/selectors.md). If you'd like to understand more about different ways to configure the navigation of your dashboard, head to [Navigation](../user-guides/navigation.md). Vizro doesn't end here, and we only covered the key features, but there is still much more to explore! You can learn: @@ -683,3 +630,12 @@ Vizro doesn't end here, and we only covered the key features, but there is still - How to add custom styling using [static assets](../user-guides/assets.md) such as custom css or JavaScript files. - How to use [Actions](../user-guides/actions.md) for example, for chart interaction or custom controls. - How to create dashboards from `yaml`, `dict` or `json` following the [dashboard guide](../user-guides/dashboard.md). + +[finalpage]: ../../assets/tutorials/dashboard/dashboard4.png +[finalpage1]: ../../assets/tutorials/dashboard/dashboard2.png +[finalpage2]: ../../assets/tutorials/dashboard/dashboard3.png +[firstpage1]: ../../assets/tutorials/dashboard/dashboard21.png +[firstpage2]: ../../assets/tutorials/dashboard/dashboard22.png +[firstpage3]: ../../assets/tutorials/dashboard/dashboard23.png +[firstpage4]: ../../assets/tutorials/dashboard/dashboard24.png +[secondpage]: ../../assets/tutorials/dashboard/dashboard3.png diff --git a/vizro-core/docs/pages/tutorials/first-dashboard.md b/vizro-core/docs/pages/tutorials/first-dashboard.md index 65fafd321..a33bb4521 100644 --- a/vizro-core/docs/pages/tutorials/first-dashboard.md +++ b/vizro-core/docs/pages/tutorials/first-dashboard.md @@ -29,22 +29,28 @@ Click on the **Run and edit this code in PyCafe** link below to live-edit the da ``` === "Result" - - [![FirstDash]][FirstDash] - - [FirstDash]: ../../assets/tutorials/dashboard/first-dashboard.png + [![FirstDash]][firstdash] + ## Can I break this code? + + When you click the link to "Edit live on PyCafe" the dashboard is running inside your browser. Any changes you make are local and you don't need to worry about breaking the code for others. Nobody else sees the changes you make unless you save a copy of the project as your own Vizro PyCafe project. + ## How can I make my own dashboards? + + You can use PyCafe to experiment with your own Vizro dashboards by dropping code onto a new project. Check out the [PyCafe documentation](https://py.cafe/docs/apps/vizro) for more information. If you need inspiration or a starting point, we make all our examples available for you to try out on PyCafe. Throughout our documentation, follow the "**Run and edit this code in PyCafe**" link below the code snippets to open them in PyCafe. ## Where next? + You are now ready to explore Vizro further, by working through the ["Explore Vizro" tutorial](explore-components.md) or by consulting the [how-to guides](../user-guides/dashboard.md). + +[firstdash]: ../../assets/tutorials/dashboard/first-dashboard.png diff --git a/vizro-core/docs/pages/user-guides/actions.md b/vizro-core/docs/pages/user-guides/actions.md index 3c811eb48..6a41ee25d 100644 --- a/vizro-core/docs/pages/user-guides/actions.md +++ b/vizro-core/docs/pages/user-guides/actions.md @@ -1,7 +1,6 @@ # How to use actions -This guide shows you how to use actions, an idea that is similar to [callbacks](https://dash.plotly.com/basic-callbacks) in `Dash`. -Many components of a dashboard (for example, [`Graph`][vizro.models.Graph] or [`Button`][vizro.models.Button]) have an optional `actions` argument, where you can enter the [`Action`][vizro.models.Action] model. +This guide shows you how to use actions, an idea that is similar to [callbacks](https://dash.plotly.com/basic-callbacks) in `Dash`. Many components of a dashboard (for example, [`Graph`][vizro.models.Graph] or [`Button`][vizro.models.Button]) have an optional `actions` argument, where you can enter the [`Action`][vizro.models.Action] model. By combining the [`Action`][vizro.models.Action] model with an action function, you can create complex dashboard interactions triggered by various events. @@ -12,22 +11,18 @@ There are already a few action functions you can reuse: ## Pre-defined actions -To attach an action to a component, you must enter the [`Action`][vizro.models.Action] model into the component's `action` argument. You can then -add a desired pre-defined action function into the `function` argument of the [`Action`][vizro.models.Action]. +To attach an action to a component, you must enter the [`Action`][vizro.models.Action] model into the component's `action` argument. You can then add a desired pre-defined action function into the `function` argument of the [`Action`][vizro.models.Action]. ??? note "Note on `Trigger`" - Currently each component has one pre-defined trigger property. A trigger property is an attribute of the component that triggers a configured action (for example, for the `Button` it is `n_click`). The below sections are guides on how to use pre-defined action functions. ### Export data -To enable downloading data, you can add the [`export_data`][vizro.actions.export_data] action function to the [`Button`][vizro.models.Button] component. -Hence, as a result, when a dashboard user now clicks the button, all data on the page will be downloaded. +To enable downloading data, you can add the [`export_data`][vizro.actions.export_data] action function to the [`Button`][vizro.models.Button] component. Hence, as a result, when a dashboard user now clicks the button, all data on the page will be downloaded. !!! example "`export_data`" - === "app.py" ```{.python pycafe-link} import vizro.models as vm @@ -61,60 +56,55 @@ Hence, as a result, when a dashboard user now clicks the button, all data on the Vizro().build(dashboard).run() ``` + === "app.yaml" ```yaml # Still requires a .py to add data to the data manager and parse YAML configuration # See yaml_version example pages: - components: - - type: graph - figure: - _target_: scatter - data_frame: iris - color: sepal_width - x: petal_length - y: sepal_length - - type: graph - figure: - _target_: histogram - data_frame: iris - color: species - x: petal_length - - type: button - text: Export data - id: export_data_button - actions: - - function: - _target_: export_data + - type: graph + figure: + _target_: scatter + data_frame: iris + color: sepal_width + x: petal_length + y: sepal_length + - type: graph + figure: + _target_: histogram + data_frame: iris + color: species + x: petal_length + - type: button + text: Export data + id: export_data_button + actions: + - function: + _target_: export_data title: Exporting ``` - === "Result" - [![Graph]][Graph] - - [Graph]: ../../assets/user_guides/actions/actions_export.png + === "Result" + [![Graph]][graph] !!! note - - Note that exported data only reflects the original dataset and any native data modifications defined with [`vm.Filter`](filters.md), [`vm.Parameter`](data.md/#parametrize-data-loading) or [`filter_interaction`](actions.md/#filter-data-by-clicking-on-chart) action. - Filters from the chart itself, such as ag-grid filters, are not included, and neither are other chart modifications, nor any data transformations in custom charts. + Note that exported data only reflects the original dataset and any native data modifications defined with [`vm.Filter`](filters.md), [`vm.Parameter`](data.md/#parametrize-data-loading) or [`filter_interaction`](actions.md/#filter-data-by-clicking-on-chart) action. Filters from the chart itself, such as ag-grid filters, are not included, and neither are other chart modifications, nor any data transformations in custom charts. ### Filter data by clicking on chart -To enable filtering when clicking on data in a source chart, you can add the -[`filter_interaction`][vizro.actions.filter_interaction] action function to the [`Graph`][vizro.models.Graph], -[`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid] components. -The [`filter_interaction`][vizro.actions.filter_interaction] is currently configured -to be triggered on click only. +To enable filtering when clicking on data in a source chart, you can add the [`filter_interaction`][vizro.actions.filter_interaction] action function to the [`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid] components. The [`filter_interaction`][vizro.actions.filter_interaction] is currently configured to be triggered on click only. To configure this chart interaction follow the steps below: -1. Add the action function to the source [`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid] -component and a list of IDs of the target charts into `targets`. +1. Add the action function to the source [`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid] component and a list of IDs of the target charts into `targets`. + ```py actions=[vm.Action(function=filter_interaction(targets=["scatter_relation_2007"]))] ``` -2. If the source chart is [`Graph`][vizro.models.Graph], enter the filter columns in the `custom_data` argument of the underlying source chart `function`. + +1. If the source chart is [`Graph`][vizro.models.Graph], enter the filter columns in the `custom_data` argument of the underlying source chart `function`. + ```py Graph(figure=px.scatter(..., custom_data=["continent"])) ``` @@ -128,7 +118,6 @@ Selecting a data point with a corresponding value of "Africa" in the continent c Here is an example of how to configure a chart interaction when the source is a [`Graph`][vizro.models.Graph] component. !!! example "Graph `filter_interaction`" - === "app.py" ```{.python pycafe-link} import vizro.models as vm @@ -171,50 +160,47 @@ Here is an example of how to configure a chart interaction when the source is a Vizro().build(dashboard).run() ``` + === "app.yaml" ```yaml # Still requires a .py to add data to the data manager and parse YAML configuration # See yaml_version example pages: - components: - - type: graph - figure: - _target_: box - data_frame: gapminder - color: continent - x: continent - y: lifeExp - custom_data: - - continent - actions: - - function: - _target_: filter_interaction - targets: - - scatter_relation_2007 - - type: graph - id: scatter_relation_2007 - figure: - _target_: scatter - data_frame: gapminder - color: continent - x: gdpPercap - y: lifeExp - size: pop + - type: graph + figure: + _target_: box + data_frame: gapminder + color: continent + x: continent + y: lifeExp + custom_data: + - continent + actions: + - function: + _target_: filter_interaction + targets: + - scatter_relation_2007 + - type: graph + id: scatter_relation_2007 + figure: + _target_: scatter + data_frame: gapminder + color: continent + x: gdpPercap + y: lifeExp + size: pop controls: - column: continent type: filter title: Filter interaction ``` - === "Result" - [![Graph2]][Graph2] - - [Graph2]: ../../assets/user_guides/actions/actions_filter_interaction.png + === "Result" + [![Graph2]][graph2] !!! note "`filter_interaction` with custom charts" - - If `filter_interaction` is assigned to a [custom chart](custom-charts.md), ensure that `custom_data` is an argument of the custom chart function, and that this argument is then passed to the underlying plotly function. - When then adding the custom chart in `vm.Graph`, ensure that `custom_data` is passed. + If `filter_interaction` is assigned to a [custom chart](custom-charts.md), ensure that `custom_data` is an argument of the custom chart function, and that this argument is then passed to the underlying plotly function. When then adding the custom chart in `vm.Graph`, ensure that `custom_data` is passed. ```py @capture("graph") @@ -227,11 +213,9 @@ Here is an example of how to configure a chart interaction when the source is a ``` - Here is an example of how to configure a chart interaction when the source is an [`AgGrid`][vizro.models.AgGrid] component. !!! example "AgGrid `filter_interaction`" - === "app.py" ```{.python pycafe-link} import vizro.models as vm @@ -271,57 +255,53 @@ Here is an example of how to configure a chart interaction when the source is an Vizro().build(dashboard).run() ``` + === "app.yaml" ```yaml # Still requires a .py to add data to the data manager and parse YAML configuration # See yaml_version example pages: - components: - - type: ag_grid - figure: - _target_: dash_ag_grid - data_frame: gapminder_2007 - actions: - - function: - _target_: filter_interaction - targets: - - scatter_relation_2007 - - type: graph - id: scatter_relation_2007 - figure: - _target_: scatter - data_frame: gapminder_2007 - color: continent - x: gdpPercap - y: lifeExp - size: pop + - type: ag_grid + figure: + _target_: dash_ag_grid + data_frame: gapminder_2007 + actions: + - function: + _target_: filter_interaction + targets: + - scatter_relation_2007 + - type: graph + id: scatter_relation_2007 + figure: + _target_: scatter + data_frame: gapminder_2007 + color: continent + x: gdpPercap + y: lifeExp + size: pop controls: - column: continent type: filter title: Filter interaction ``` - === "Result" - [![Table]][Table] - - [Table]: ../../assets/user_guides/actions/actions_table_filter_interaction.png + === "Result" + [![Table]][table] ### Customize pre-defined actions + Many pre-defined actions are customizable which helps to achieve a more specific goal. Refer to the [API reference][vizro.actions] for the options available. ## Custom actions -If you require an action that isn't available as a pre-defined option, you can create a custom action function. -Refer to our [user guide on custom actions](custom-actions.md) for more information. +If you require an action that isn't available as a pre-defined option, you can create a custom action function. Refer to our [user guide on custom actions](custom-actions.md) for more information. ## Chain actions -The `actions` parameter for the different screen components accepts a `list` of [`Action`][vizro.models.Action] models. -This means that it's possible to chain together a list of actions that are executed by triggering only one component. -The order of action execution is guaranteed, and the next action in the list will start executing only when the previous one is completed. +The `actions` parameter for the different screen components accepts a `list` of [`Action`][vizro.models.Action] models. This means that it's possible to chain together a list of actions that are executed by triggering only one component. The order of action execution is guaranteed, and the next action in the list will start executing only when the previous one is completed. !!! example "Actions chaining" - === "app.py" ```{.python pycafe-link extra-requirements="openpyxl"} import vizro.models as vm @@ -368,44 +348,49 @@ The order of action execution is guaranteed, and the next action in the list wil Vizro().build(dashboard).run() ``` + === "app.yaml" ```yaml pages: - components: - - type: graph - id: scatter - figure: - _target_: scatter - data_frame: iris - color: sepal_width - x: petal_length - y: sepal_length - - type: graph - id: hist - figure: - _target_: histogram - data_frame: iris - color: species - x: petal_length - - type: button - text: Export data - id: export_data_button - actions: - - function: - _target_: export_data - targets: - - scatter - - function: - _target_: export_data - targets: - - hist - file_format: xlsx + - type: graph + id: scatter + figure: + _target_: scatter + data_frame: iris + color: sepal_width + x: petal_length + y: sepal_length + - type: graph + id: hist + figure: + _target_: histogram + data_frame: iris + color: species + x: petal_length + - type: button + text: Export data + id: export_data_button + actions: + - function: + _target_: export_data + targets: + - scatter + - function: + _target_: export_data + targets: + - hist + file_format: xlsx controls: - type: filter column: species title: Exporting ``` + === "Result" - [![Graph3]][Graph3] + [![Graph3]][graph3] - [Graph3]: ../../assets/user_guides/actions/actions_chaining.png +[graph]: ../../assets/user_guides/actions/actions_export.png +[graph2]: ../../assets/user_guides/actions/actions_filter_interaction.png +[graph3]: ../../assets/user_guides/actions/actions_chaining.png +[table]: ../../assets/user_guides/actions/actions_table_filter_interaction.png diff --git a/vizro-core/docs/pages/user-guides/assets.md b/vizro-core/docs/pages/user-guides/assets.md index ae87f5527..87c79fb07 100644 --- a/vizro-core/docs/pages/user-guides/assets.md +++ b/vizro-core/docs/pages/user-guides/assets.md @@ -1,11 +1,8 @@ # How to add static assets -This guide shows you how to add static assets to your dashboard. Static assets are images that you would like to show in your dashboard, or custom CSS and JS files -with which you would like to enhance/change the appearance of your dashboard. +This guide shows you how to add static assets to your dashboard. Static assets are images that you would like to show in your dashboard, or custom CSS and JS files with which you would like to enhance/change the appearance of your dashboard. -To add images, custom CSS or JS files, create a folder named `assets` in the root of your app directory and insert your files. -Assets included in that folder are automatically served after serving Vizro's static files via the `external_stylesheets` and `external_scripts` arguments of [Dash](https://dash.plotly.com/external-resources#adding-external-css/javascript). -The user's `assets` folder thus always takes precedence. +To add images, custom CSS or JS files, create a folder named `assets` in the root of your app directory and insert your files. Assets included in that folder are automatically served after serving Vizro's static files via the `external_stylesheets` and `external_scripts` arguments of [Dash](https://dash.plotly.com/external-resources#adding-external-css/javascript). The user's `assets` folder thus always takes precedence. ```text title="Example folder structure" ├── app.py @@ -21,15 +18,11 @@ The user's `assets` folder thus always takes precedence. ``` !!! warning "Dash Bootstrap Themes" - - Note that Vizro is currently not compatible with [Dash Bootstrap Themes](https://dash-bootstrap-components.opensource.faculty.ai/docs/themes/). - Adding a Bootstrap stylesheet will have no visual effect on the [components](https://vizro.readthedocs.io/en/stable/pages/user_guides/components/) included in Vizro. - + Note that Vizro is currently not compatible with [Dash Bootstrap Themes](https://dash-bootstrap-components.opensource.faculty.ai/docs/themes/). Adding a Bootstrap stylesheet will have no visual effect on the [components](https://vizro.readthedocs.io/en/stable/pages/user_guides/components/) included in Vizro. ## Change the favicon -To change the default favicon (website icon appearing in the browser tab), add a file named `favicon.ico` to your `assets` folder. -For more information, see the [Dash documentation](https://dash.plotly.com/external-resources#changing-the-favicon). +To change the default favicon (website icon appearing in the browser tab), add a file named `favicon.ico` to your `assets` folder. For more information, see the [Dash documentation](https://dash.plotly.com/external-resources#changing-the-favicon). ## Add a logo image @@ -41,52 +34,36 @@ If an image named `logo.` is present in the assets folder, Vizro auto
### Theme-specific logos
-You can also supply two images named `logo_dark.` and `logo_light.` to switch logos
-based on the theme (dark or light).
+You can also supply two images named `logo_dark.` and `logo_light.` to switch logos based on the theme (dark or light).
Note that both `logo_light.` and `logo_dark.` must be supplied together, unless a single `logo.` is supplied for both light and dark themes. That is, the valid configurations are as follows:
-* Single logo: Supply only `logo.`, which is used for dark and light themes. **Do not include light and dark theme logos**.
-* Theme logos: Supply both `logo_light.` and `logo_dark.` for light/dark themes. **Do not include `logo.`**.
-* No logo: No logo images supplied.
+- Single logo: Supply only `logo.`, which is used for dark and light themes. **Do not include light and dark theme logos**.
+- Theme logos: Supply both `logo_light.` and `logo_dark.` for light/dark themes. **Do not include `logo.`**.
+- No logo: No logo images supplied.
-
-
+ 
## Change the `assets` folder path
-If you do not want to place your `assets` folder in the root directory of your app, you can
-specify an alternative path through the `assets_folder` argument of the [`Vizro`][vizro.Vizro] class.
-
-```python
-from vizro import Vizro
-import vizro.models as vm
-
-page =
-dashboard = vm.Dashboard(pages=[page])
-app = Vizro(assets_folder="path/to/assets/folder").build(dashboard).run()
+If you do not want to place your `assets` folder in the root directory of your app, you can specify an alternative path through the `assets_folder` argument of the [`Vizro`][vizro.Vizro] class.
+```python
+Vizro(assets_folder="path/to/assets/folder").build(dashboard).run()
```
-Note that in the example above, you still need to configure your [`Page`][vizro.models.Page].
-See more information in the [Pages User Guide](pages.md).
-
-
## Include a meta tags image
-Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat
-clients. To include an image in the preview, place an image file in the assets folder named `app.` or
-`logo.`. Vizro searches the assets folder and uses the first one it finds.
+Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat clients. To include an image in the preview, place an image file in the assets folder named `app.` or `logo.`. Vizro searches the assets folder and uses the first one it finds.
Image types of `apng`, `avif`, `gif`, `jpeg`, `jpg`, `png`, `svg`, and `webp` are supported.
-
## Order of serving CSS files
CSS properties will be applied with the last served file taking precedence. The order of serving is:
1. Dash built-in stylesheets
-2. Vizro built-in stylesheets
-3. User assets folder stylesheets
+1. Vizro built-in stylesheets
+1. User assets folder stylesheets
Within each of these categories, individual files are served in alphanumeric order.
diff --git a/vizro-core/docs/pages/user-guides/card-button.md b/vizro-core/docs/pages/user-guides/card-button.md
index 08103c472..3c5ad2d7d 100755
--- a/vizro-core/docs/pages/user-guides/card-button.md
+++ b/vizro-core/docs/pages/user-guides/card-button.md
@@ -4,12 +4,10 @@ This guide shows you how to use cards and buttons to visualize and interact with
## Cards
-The [`Card`][vizro.models.Card] is a flexible and extensible component that enables customization via markdown text.
-Refer to any online guide for [basic markdown usage](https://markdown-guide.readthedocs.io/en/latest/).
+The [`Card`][vizro.models.Card] is a flexible and extensible component that enables customization via markdown text. Refer to any online guide for [basic markdown usage](https://markdown-guide.readthedocs.io/en/latest/).
You can add a [`Card`][vizro.models.Card] to your dashboard by inserting the [`Card`][vizro.models.Card] into the `components` argument of the [`Page`][vizro.models.Page].
-
!!! example "Card"
=== "app.py"
```{.python pycafe-link}
@@ -32,28 +30,26 @@ You can add a [`Card`][vizro.models.Card] to your dashboard by inserting the [`C
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - text: |
- Commodi repudiandae consequuntur voluptatum.
- title: Card Title
- type: card
- title: Card
+ - components:
+ - text: |
+ Commodi repudiandae consequuntur voluptatum.
+ title: Card Title
+ type: card
+ title: Card
```
- === "Result"
- [![Card]][Card]
- [Card]: ../../assets/user_guides/components/card.png
+ === "Result"
+ [![Card]][card]
### Customize card text
-The [`Card`][vizro.models.Card] uses the `dcc.Markdown` component from Dash as its underlying text component.
-For more details on customizing the markdown text, refer to the [`dcc.Markdown` component documentation](https://dash.plotly.com/dash-core-components/markdown).
-Based on examples from Dash, the [`Card`][vizro.models.Card] model supports the following:
+The [`Card`][vizro.models.Card] uses the `dcc.Markdown` component from Dash as its underlying text component. For more details on customizing the markdown text, refer to the [`dcc.Markdown` component documentation](https://dash.plotly.com/dash-core-components/markdown). Based on examples from Dash, the [`Card`][vizro.models.Card] model supports the following:
- Headers
- Emphasis
@@ -130,58 +126,58 @@ Based on examples from Dash, the [`Card`][vizro.models.Card] model supports the
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - text: |
- # Header level 1
-
- ## Header level 2
diff --git a/vizro-ai/changelog.d/20240917_174515_alexey_snigir_automatic_vizro_ai_score_tests.md b/vizro-ai/changelog.d/20240917_174515_alexey_snigir_automatic_vizro_ai_score_tests.md
index f1f65e73c..aa45b72f1 100644
--- a/vizro-ai/changelog.d/20240917_174515_alexey_snigir_automatic_vizro_ai_score_tests.md
+++ b/vizro-ai/changelog.d/20240917_174515_alexey_snigir_automatic_vizro_ai_score_tests.md
@@ -10,36 +10,42 @@ Uncomment the section that is right (remove the HTML comment wrapper).
- 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))
-->
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
@@ -17,14 +16,11 @@ and are responsible for obtaining their own suitable API key for the relevant mo
Users acknowledge and agree that:
-Any results, options, data, recommendations, analyses, code,
-or other information (“Outputs”) generated by any third-party generative AI tools (“GenAI Tools”) may contain some inaccuracies, biases, illegitimate, potentially infringing,
-or otherwise inappropriate content that may be mistaken, discriminatory, or misleading.
+Any results, options, data, recommendations, analyses, code, or other information (“Outputs”) generated by any third-party generative AI tools (“GenAI Tools”) may contain some inaccuracies, biases, illegitimate, potentially infringing, or otherwise inappropriate content that may be mistaken, discriminatory, or misleading.
McKinsey & Company:
-(i) expressly disclaims the accuracy, adequacy, timeliness, reliability, merchantability, fitness for a particular purpose, non-infringement,
-safety or completeness of any Outputs,
+(i) expressly disclaims the accuracy, adequacy, timeliness, reliability, merchantability, fitness for a particular purpose, non-infringement, safety or completeness of any Outputs,
(ii) shall not be liable for any errors, omissions, or other defects in, delays or interruptions in such Outputs, or for any actions taken in reliance thereon, and
@@ -32,7 +28,6 @@ safety or completeness of any Outputs,
The Outputs shall be verified and validated by the users and shall not be used without human oversight and as a sole basis for making decisions impacting individuals.
-Users remain solely responsible for the use of the Output, in particular, the users will need to determine the level of human oversight needed to be given the context and use case,
-as well as for informing the users’ personnel and other affected users about the nature of the GenAI Output.
-Users are also fully responsible for their decisions, actions, use of Vizro and Vizro-AI and compliance with applicable laws, rules, and regulations, including but not limited to confirming that the Outputs do not infringe any third-party rights.
+Users remain solely responsible for the use of the Output, in particular, the users will need to determine the level of human oversight needed to be given the context and use case, as well as for informing the users’ personnel and other affected users about the nature of the GenAI Output. Users are also fully responsible for their decisions, actions, use of Vizro and Vizro-AI and compliance with applicable laws, rules, and regulations, including but not limited to confirming that the Outputs do not infringe any third-party rights.
+
diff --git a/vizro-ai/docs/pages/explanation/faq.md b/vizro-ai/docs/pages/explanation/faq.md
index 46dfcd2ce..9eb0fad6f 100644
--- a/vizro-ai/docs/pages/explanation/faq.md
+++ b/vizro-ai/docs/pages/explanation/faq.md
@@ -3,20 +3,11 @@
## Who works on Vizro-AI?
### Current team members
-[Alexey Snigir](https://github.com/l0uden),
-[Anna Xiong](https://github.com/Anna-Xiong),
-[Antony Milne](https://github.com/antonymilne),
-[Dan Dumitriu](https://github.com/dandumitriu1),
-[Huong Li Nguyen](https://github.com/huong-li-nguyen),
-[Jo Stichbury](https://github.com/stichbury),
-[Joseph Perkins](https://github.com/Joseph-Perkins),
-[Lingyi Zhang](https://github.com/lingyielia),
-[Maximilian Schulz](https://github.com/maxschulz-COL),
-[Nadija Graca](https://github.com/nadijagraca),
-[Petar Pejovic](https://github.com/petar-qb).
-With thanks to Sam Bourton and Stephen Xu for sponsorship, inspiration and guidance, plus everyone else who helped to test, guide, support and encourage development.
+[Alexey Snigir](https://github.com/l0uden), [Anna Xiong](https://github.com/Anna-Xiong), [Antony Milne](https://github.com/antonymilne), [Dan Dumitriu](https://github.com/dandumitriu1), [Huong Li Nguyen](https://github.com/huong-li-nguyen), [Jo Stichbury](https://github.com/stichbury), [Joseph Perkins](https://github.com/Joseph-Perkins), [Lingyi Zhang](https://github.com/lingyielia), [Maximilian Schulz](https://github.com/maxschulz-COL), [Nadija Graca](https://github.com/nadijagraca), [Petar Pejovic](https://github.com/petar-qb).
+With thanks to Sam Bourton and Stephen Xu for sponsorship, inspiration and guidance, plus everyone else who helped to test, guide, support and encourage development.
## Which large language models are supported by vizro-ai?
+
Refer to [supported models](../user-guides/customize-vizro-ai.md#supported-models) in `vizro-ai` docs.
diff --git a/vizro-ai/docs/pages/explanation/safeguard.md b/vizro-ai/docs/pages/explanation/safeguard.md
index f4311fcd6..aacd2c503 100644
--- a/vizro-ai/docs/pages/explanation/safeguard.md
+++ b/vizro-ai/docs/pages/explanation/safeguard.md
@@ -1,88 +1,74 @@
# Safeguard dynamic code execution in Vizro-AI
-Vizro-AI uses the `exec()` statement in Python to run generated code from large language models (LLMs) for
-self-debugging and automatic visual rendering in methods such as `.get_fig_object()` and `VizroAI.plot()`.
-One of the primary concerns is the potential for malicious code to access or change critical system resources or data.
+Vizro-AI uses the `exec()` statement in Python to run generated code from large language models (LLMs) for self-debugging and automatic visual rendering in methods such as `.get_fig_object()` and `VizroAI.plot()`. One of the primary concerns is the potential for malicious code to access or change critical system resources or data.
## Understand `exec()`
-The `exec()` function enables the dynamic execution of Python programs which can either be a string or object code.
-While it offers great flexibility, it also poses a significant security risk, especially when executing untrusted code.
+The `exec()` function enables the dynamic execution of Python programs which can either be a string or object code. While it offers great flexibility, it also poses a significant security risk, especially when executing untrusted code.
## Safeguarding code execution
-While we have made considerable efforts to safeguard its usage by limiting the usage to specific modules and functions and by restricting certain built-in operations,
-these measures cannot guarantee absolute security. It is imperative for users to take extra precautions.
+While we have made considerable efforts to safeguard its usage by limiting the usage to specific modules and functions and by restricting certain built-in operations, these measures cannot guarantee absolute security. It is imperative for users to take extra precautions.
### Our effort on safeguarding code execution in Vizro-AI
-To help to mitigate these risks, we limit the execution of certain modules and functions.
-One approach is to use Python's built-in `sys` module to restrict access to unsafe modules or functions.
-By defining a whitelist of safe modules and packages and restricting certain built-in functions.
+To help to mitigate these risks, we limit the execution of certain modules and functions. One approach is to use Python's built-in `sys` module to restrict access to unsafe modules or functions. By defining a whitelist of safe modules and packages and restricting certain built-in functions.
!!! Warning
-
- While some measures have been put in place to help safeguard against known vulnerabilities,
- it is important to run such systems in an isolated environment and avoid providing malicious inputs,
- since such **safeguards can never be 100% effective**. Always ensure the security infrastructure when implementing and using such systems.
+ While some measures have been put in place to help safeguard against known vulnerabilities, it is important to run such systems in an isolated environment and avoid providing malicious inputs, since such **safeguards can never be 100% effective**. Always ensure the security infrastructure when implementing and using such systems.
The white lists indicate allowed packages and built-in functions.
- The red lists represent potentially
- unsafe methods or operations that are restricted.
+ The red lists represent potentially unsafe methods or operations that are restricted.
The lists below are a reflection of the security and functionality we have implemented with Vizro-AI:
-??? success "Whitelisted Packages"
+
- - `pandas`
- - `numpy`
- - `vizro`
- - `plotly`
- - `datetime`
- - `matplotlib`
- - `dash`
- - `scipy`
- - `sklearn`
+??? success "Whitelisted Packages"
+ - `pandas`
+ - `numpy`
+ - `vizro`
+ - `plotly`
+ - `datetime`
+ - `matplotlib`
+ - `dash`
+ - `scipy`
+ - `sklearn`
??? success "Whitelisted Builtins"
-
- - abs
- - len
- - max
- - min
- - print
- - sum
- - None
- - False
- - True
- - dict
- - enumerate
- - float
- - int
- - list
- - map
- - str
- - tuple
+ - abs
+ - len
+ - max
+ - min
+ - print
+ - sum
+ - None
+ - False
+ - True
+ - dict
+ - enumerate
+ - float
+ - int
+ - list
+ - map
+ - str
+ - tuple
??? failure "Redlisted Class Methods"
-
- subclasses
- builtins
??? failure "Redlisted Data Handling Methods and Formats"
-
- Various data file formats (such as .csv, .tsv, .xlsx, .json, and so on)
- Specific methods related to data input/output operations (such as .to_csv, .read_excel, .loadtxt)
+
+
### Safeguard for user environment and input
-- **Isolated environment**: Always run code in an isolated or contained environment, such as a virtual environment,
- virtual machine or container, to minimize potential harm to the primary system.
+- **Isolated environment**: Always run code in an isolated or contained environment, such as a virtual environment, virtual machine or container, to minimize potential harm to the primary system.
-- **Avoid malicious input**: Never feed untrusted or malicious input. Regardless of safeguards,
- there's always a risk associated with executing dynamic code.
- It remains the user's responsibility to ensure the safety and appropriateness of executing any generated code,
- particularly in sensitive or critical contexts.
+- **Avoid malicious input**: Never feed untrusted or malicious input. Regardless of safeguards, there's always a risk associated with executing dynamic code. It remains the user's responsibility to ensure the safety and appropriateness of executing any generated code, particularly in sensitive or critical contexts.
- **Accessible to trusted users**: Only trusted users should be given access to the system to run Vizro-AI.
diff --git a/vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md b/vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md
index 489e5aa33..fc54596bb 100644
--- a/vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md
+++ b/vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md
@@ -4,60 +4,63 @@ Vizro-AI uses generative AI models because large language models (LLMs) represen
We recommend users research and understand the selected model before using `vizro_ai` package.
-Users are encouraged to treat AI-generated content as supplementary, **always apply human judgment**,
-approach with caution, review the relevant [disclaimer](disclaimer.md) page, and consider the following:
+Users are encouraged to treat AI-generated content as supplementary, **always apply human judgment**, approach with caution, review the relevant [disclaimer](disclaimer.md) page, and consider the following:
+
+
### 1. Hallucination and misrepresentation
Generative models can potentially generate information while appearing factual, being entirely fictitious or misleading.
+
-The vendor models might lack real-time knowledge or events beyond its last updates.
-`vizro_ai` output may vary and you should always verify critical information.
-It is the user's responsibility to discern the accuracy, consistent, and reliability of the generated content.
+
+The vendor models might lack real-time knowledge or events beyond its last updates. `vizro_ai` output may vary and you should always verify critical information. It is the user's responsibility to discern the accuracy, consistent, and reliability of the generated content.
+
### 2. Unintended and sensitive output
+
-The outputs from these models can be unexpected, inappropriate, or even harmful.
-Users as human in the loop is an essential part. Users must check and interpret the final output.
-It is necessary to approach the generated content with caution, especially when shared or applied in various contexts.
+
+The outputs from these models can be unexpected, inappropriate, or even harmful. Users as human in the loop is an essential part. Users must check and interpret the final output. It is necessary to approach the generated content with caution, especially when shared or applied in various contexts.
+
### 3. Data privacy
+
-Your data is sent to model vendors if you connect to LLMs via their APIs.
-For example, if you connect to the model from OpenAI, your data will be sent to OpenAI via their API.
-Users should be cautious about sharing or inputting any personal or sensitive information.
+
+Your data is sent to model vendors if you connect to LLMs via their APIs. For example, if you connect to the model from OpenAI, your data will be sent to OpenAI via their API. Users should be cautious about sharing or inputting any personal or sensitive information.
+
### 4. Bias and fairness
+
-Generative AI can exhibit biases present in their training data.
-Users need to be aware of and navigate potential biases in generated outputs and be cautious when interpreting the generated content.
+
+Generative AI can exhibit biases present in their training data. Users need to be aware of and navigate potential biases in generated outputs and be cautious when interpreting the generated content.
+
### 5. Malicious use
+
+
These models can be exploited for various malicious activities. Users should be cautious about how and where they deploy and access such models.
It's crucial for users to remain informed, cautious, and ethical in their applications.
-
## Dependencies, code scanners, and information security
-It may occur that dependencies of `vizro_ai` get flagged by code scanners and other information security tools. As a consequence it may happen that
-`vizro_ai` also get flagged.
+It may occur that dependencies of `vizro_ai` get flagged by code scanners and other information security tools. As a consequence it may happen that `vizro_ai` also get flagged.
-While we aim to resolve any flagged issues as soon as possible, there may not always be an immediate available fix, especially in a dynamic environment such as generative AI. We encourage users to investigate if any flagged information security issues are actually related
-to any functionality used in our code base or if they only concern functionality outside the scope of `vizro_ai`.
+While we aim to resolve any flagged issues as soon as possible, there may not always be an immediate available fix, especially in a dynamic environment such as generative AI. We encourage users to investigate if any flagged information security issues are actually related to any functionality used in our code base or if they only concern functionality outside the scope of `vizro_ai`.
In case those issues are related to code execution, note that `vizro_ai` has its own process of executing dynamic code (see [Safeguard Execution of Dynamic Code](safeguard.md)), and does not rely on its dependencies to do so.
-
## Execution of dynamic code in Vizro-AI
-The `exec()` statement is used in `vizro_ai`. It enables dynamic execution of Python programs which can be powerful, but can also pose security risk
-if used without caution. When paired with outputs from generative models, there is potential for unintended or malicious code execution.
+The `exec()` statement is used in `vizro_ai`. It enables dynamic execution of Python programs which can be powerful, but can also pose security risk if used without caution. When paired with outputs from generative models, there is potential for unintended or malicious code execution.
Users must exercise caution when executing code generated by or influenced by AI models. It's essential to:
@@ -69,11 +72,9 @@ Users must exercise caution when executing code generated by or influenced by AI
To learn more, refer to the section that describes how to [safeguard execution of dynamic code](safeguard.md).
-
## Debugging in Vizro-AI with LangSmith and LangFuse
-[LangSmith](https://docs.smith.langchain.com/) and [LangFuse](https://langfuse.com/docs) are tools designed to enhance transparency and interpretability in AI workflows.
-To improve debugging and traceability, you can use the advanced observability and evaluation features of these tools with Vizro-AI.
+[LangSmith](https://docs.smith.langchain.com/) and [LangFuse](https://langfuse.com/docs) are tools designed to enhance transparency and interpretability in AI workflows. To improve debugging and traceability, you can use the advanced observability and evaluation features of these tools with Vizro-AI.
To ensure responsible use, review their data privacy and security policies. See [LangFuse Data Security & Privacy ](https://langfuse.com/docs/data-security-privacy) and [LangSmith Privacy Policy](https://www.langchain.com/privacy-policy) site for more details.
diff --git a/vizro-ai/docs/pages/tutorials/quickstart-dashboard.md b/vizro-ai/docs/pages/tutorials/quickstart-dashboard.md
index c29607baa..2118112d7 100644
--- a/vizro-ai/docs/pages/tutorials/quickstart-dashboard.md
+++ b/vizro-ai/docs/pages/tutorials/quickstart-dashboard.md
@@ -8,12 +8,11 @@ You may also want to review the [Vizro dashboard tutorial](https://vizro.readthe
If you haven't already installed Vizro-AI and set up the API key for OpenAI, follow the [installation guide](../user-guides/install.md).
-
## 2. Open a Notebook
+
A good way to initially explore Vizro-AI is from inside a Jupyter Notebook.
??? "If you haven't used Jupyter before..."
-
You may need to install the Jupyter package if you . From the terminal window:
```bash
@@ -39,6 +38,7 @@ print(vizro_ai.__version__)
You should see a return output of the form `x.y.z`.
## 3. Instantiate VizroAI
+
```py
from vizro_ai import VizroAI
@@ -46,6 +46,7 @@ vizro_ai = VizroAI()
```
## 4. Prepare the data
+
Next, prepare the data to pass to Vizro-AI. In this example, we use the [gapminder data](https://plotly.com/python-api-reference/generated/plotly.express.data.html#plotly.express.data.gapminder).
```py
@@ -87,6 +88,7 @@ dashboard = vizro_ai.dashboard([df], user_question)
The call to `dashboard()` initiates dashboard generation. By default, it generates the Vizro `Dashboard` Object.
## 7. Build dashboard
+
Once dashboard generation is complete, launch the dashboard with `build()`.
```py
@@ -95,7 +97,6 @@ Vizro().build(dashboard).run()
```
!!! example "Generated dashboard"
-
=== "Code for the cell"
```py
from vizro import Vizro
@@ -119,6 +120,6 @@ Vizro().build(dashboard).run()
```
=== "Result"
- [![VizroAIDashboardPage1]][VizroAIDashboardPage1]
+ [![VizroAIDashboardPage1]][vizroaidashboardpage1]
- [VizroAIDashboardPage1]: ../../assets/tutorials/dashboard/dashboard0_page1.png
+[vizroaidashboardpage1]: ../../assets/tutorials/dashboard/dashboard0_page1.png
diff --git a/vizro-ai/docs/pages/tutorials/quickstart.md b/vizro-ai/docs/pages/tutorials/quickstart.md
index 17d673927..64574cd77 100644
--- a/vizro-ai/docs/pages/tutorials/quickstart.md
+++ b/vizro-ai/docs/pages/tutorials/quickstart.md
@@ -1,20 +1,24 @@
# Chart generation
+
This tutorial introduces you to chart generation using Vizro-AI. It explains the basics of creating a plotly chart that can be added to a Vizro dashboard. When you have followed it, you are set up to explore the Vizro and Vizro-AI packages further.
+
### 1. Install Vizro-AI and its dependencies
+
If you haven't already installed Vizro-AI and set up the API key for OpenAI, follow the [installation guide](../user-guides/install.md).
+
### 2. Open a Jupyter Notebook
+
A good way to initially explore Vizro-AI is from inside a Jupyter Notebook.
??? "If you haven't used Jupyter before..."
-
You may need to install the Jupyter package if you . From the terminal window:
```bash
@@ -40,7 +44,9 @@ print(vizro_ai.__version__)
You should see a return output of the form `x.y.z`.
+
### 3. Create your first plotly chart using Vizro-AI
+
Let's create a chart to illustrate the GDP of various continents while including a reference line for the average. We give Vizro-AI the English language instruction "*describe the composition of GDP in continent and color by continent, and add a horizontal line for avg GDP*".
@@ -54,12 +60,12 @@ import vizro.plotly.express as px
df = px.data.gapminder()
```
-
Next, we instantiate `VizroAI`:
```python
vizro_ai = VizroAI()
```
+
To learn how to customize the `VizroAI` class, check out the guide on [how to customize models](../user-guides/customize-vizro-ai.md).
Finally, we call the `plot()` method with our English language instruction, to generate the visualization:
@@ -74,7 +80,6 @@ vizro_ai.plot(
```
!!! warning "Help! The LLM request was unauthorized"
-
If you see an error similar to this, your LLM API key is not valid:
`INFO:httpx:HTTP Request: POST https://api.openai.com/v1/chat/completions "HTTP/1.1 401 Unauthorized"`
@@ -83,12 +88,11 @@ vizro_ai.plot(
`export OPENAI_API_KEY="sk-YOURKEY"`.
- The call above makes the API key available from that terminal instance. If you want to access Vizro-AI from a Notebook, you should then run `jupyter notebook` (or just work within that terminal to run your Python script in `app.py`. When you restart the terminal, you'll need to call `export` again.
+ The call above makes the API key available from that terminal instance. If you want to access Vizro-AI from a Notebook, you should then run `jupyter notebook` (or just work within that terminal to run your Python script in `app.py`. When you restart the terminal, you'll need to call `export` again.
And that's it! By passing the prepared data and written visualization request, Vizro-AI takes care of the processing. It generates the necessary code for data manipulation and chart creation, and returns the chart by executing the generated code.
!!! example "Vizro-AI Syntax"
-
=== "Code for the cell"
```py
import vizro.plotly.express as px
@@ -104,38 +108,40 @@ And that's it! By passing the prepared data and written visualization request, V
Make sure to take average over continent.""",
)
```
- === "Result"
- [![LineGraph]][LineGraph]
- [LineGraph]: ../../assets/tutorials/chart/GDP_Composition_Graph.png
+ === "Result"
+ [![LineGraph]][linegraph]
The chart created is interactive: you can hover over the data for more information.
Passing `return_elements=True` to the `plot()` method returns an object, which includes the code along with a set of insights to explain the rendered chart in detail. You can then use the code within a Vizro dashboard as illustrated in the [Vizro documentation](https://vizro.readthedocs.io/en/stable/pages/tutorials/explore-components/#22-add-further-components). For the line graph above, the code returned may be as follows:
!!! example "Returned by Vizro-AI"
-
```python
from vizro.models.types import capture
import vizro.plotly.express as px
import pandas as pd
- @capture('graph')
+
+
+ @capture("graph")
def custom_chart(data_frame):
- df = data_frame.groupby(['year', 'continent'])['gdpPercap'].mean().unstack().reset_index()
- fig = px.line(df, x='year', y=['Africa', 'Americas', 'Asia', 'Europe', 'Oceania'])
+ df = data_frame.groupby(["year", "continent"])["gdpPercap"].mean().unstack().reset_index()
+ fig = px.line(df, x="year", y=["Africa", "Americas", "Asia", "Europe", "Oceania"])
return fig
+
fig = custom_chart(data_frame=df)
```
+
### 4. Get an explanation with your chart
+
Let's create another example to illustrate the code and insights returned when passing `return_elements=True` as a parameter to `plot()`:
!!! example "Specify `return_elements=True`"
-
=== "Code for the cell"
```py
res = vizro_ai.plot(df, "show me the geo distribution of life expectancy", return_elements=True)
@@ -143,8 +149,10 @@ Let's create another example to illustrate the code and insights returned when p
print(res.chart_insights)
print(res.code_explanation)
```
+
=== "Result"
Code
+
```py
import plotly.express as px
@@ -164,13 +172,17 @@ Let's create another example to illustrate the code and insights returned when p
)
return fig
```
+
Chart insights
+
```
This choropleth map visualizes the global distribution of life expectancy across
different countries. It highlights variations and trends in life expectancy,
providing a clear visual representation of geographical disparities.
```
+
Code explanation
+
```
- Import Plotly Express.
- Create a choropleth map using the `px.choropleth` function.
@@ -180,13 +192,14 @@ Let's create another example to illustrate the code and insights returned when p
- Update layout to enhance map readability and aesthetics.
```
- [GeoDistribution]: ../../assets/tutorials/chart/GeoDistribution.png
-
+
### 5. Explore further
-
+
Congratulations! You have created your first charts with Vizro-AI and you are ready to explore further.
A good place to start would be to review the different how-to guides to learn [the different ways to run Vizro-AI](../user-guides/run-vizro-ai.md), [how to create advanced charts](../user-guides/create-advanced-charts.md) and [how to add your Vizro-AI charts to a Vizro dashboard](../user-guides/add-generated-chart-usecase.md). You may also want to review the tutorial on [how to generate a Vizro dashboard with Vizro-AI](quickstart-dashboard.md)
+
+[linegraph]: ../../assets/tutorials/chart/GDP_Composition_Graph.png
diff --git a/vizro-ai/docs/pages/user-guides/add-generated-chart-usecase.md b/vizro-ai/docs/pages/user-guides/add-generated-chart-usecase.md
index 922fcb3b4..60eb24100 100644
--- a/vizro-ai/docs/pages/user-guides/add-generated-chart-usecase.md
+++ b/vizro-ai/docs/pages/user-guides/add-generated-chart-usecase.md
@@ -2,17 +2,15 @@
This guide explains the different ways in which you can add a chart generated by Vizro-AI to an existing [Vizro dashboard](https://github.com/mckinsey/vizro/tree/main/vizro-core).
-## Use Vizro-AI's generated code
+## Use Vizro-AI's generated code
1. Create a chart with Vizro-AI that you would like to visualize in a dashboard.
In this example, we aim to create a chart that illustrates the population development of each continent over time. To gain deeper insights and access the underlying code responsible for generating the chart, include `return_elements=True` in the `plot()` method. Let's execute the provided code and examine the outcome.
!!! example "Vizro-AI chart"
-
=== "Code for the cell"
-
- ```py
+ ```python
import vizro_ai
from vizro_ai import VizroAI
import vizro.plotly.express as px
@@ -23,23 +21,25 @@ This guide explains the different ways in which you can add a chart generated by
df = px.data.gapminder()
vizro_ai = VizroAI(model="gpt-4o")
- result = vizro_ai.plot(df,
- """Plot a bubble chart to show the changes in life expectancy
- and GDP per capita for each country over time.
- Color the bubbles by continent.
- Add animation on yearly basis, and do not use facets.
- Put the legend on top""", return_elements=True)
+ result = vizro_ai.plot(
+ df,
+ """Plot a bubble chart to show the changes in life expectancy
+ and GDP per capita for each country over time.
+ Color the bubbles by continent.
+ Add animation on yearly basis, and do not use facets.
+ Put the legend on top""",
+ return_elements=True,
+ )
- print(f"Insight:\n{result.chart_insights}\n" )
- print(f"Code explanation:\n{result.code_explanation}\n\nCode:\n{result.code_vizro}\n" )
+ print(f"Insight:\n{result.chart_insights}\n")
+ print(f"Code explanation:\n{result.code_explanation}\n\nCode:\n{result.code_vizro}\n")
result.get_fig_object(df).show()
```
- === "Result"
- [![VizroAIChart]][VizroAIChart]
- [VizroAIChart]: ../../assets/user_guides/vizro-ai-chart.png
+ === "Result"
+ [![VizroAIChart]][vizroaichart]
-2. Insert the resulting chart into a dashboard.
+1. Insert the resulting chart into a dashboard.
Once you are satisfied with the chart, you can add it to a [Vizro](https://github.com/mckinsey/vizro/tree/main/vizro-core) dashboard.
@@ -62,11 +62,9 @@ This guide explains the different ways in which you can add a chart generated by
return fig
```
-The `custom_chart` function is an example of the [custom chart](https://vizro.readthedocs.io/en/stable/pages/user-guides/custom-charts). It returns a `go.Figure()` object.
-This object must then be passed to the `figure` argument of the Vizro [Graph](https://vizro.readthedocs.io/en/stable/pages/user-guides/graph) model.
+The `custom_chart` function is an example of the [custom chart](https://vizro.readthedocs.io/en/stable/pages/user-guides/custom-charts). It returns a `go.Figure()` object. This object must then be passed to the `figure` argument of the Vizro [Graph](https://vizro.readthedocs.io/en/stable/pages/user-guides/graph) model.
!!! example "Vizro-AI chart within vizro dashboard"
-
=== "Code for the cell"
```py hl_lines="8-23 31"
from vizro import Vizro
@@ -100,35 +98,30 @@ This object must then be passed to the `figure` argument of the Vizro [Graph](ht
title = 'Demographics',
components = [
vm.Graph(figure=custom_chart(df)),
- vm.Graph(figure = px.box(df,
- x='continent',
- y='lifeExp',
- color='continent',
- title='Life Expectancy per Continent'))],
+ vm.Graph(
+ figure=px.box(
+ df, x='continent', y='lifeExp', color='continent', title='Life Expectancy per Continent'
+ )
+ )
+ ],
controls = [
vm.Filter(column='country'),
vm.Filter(column='continent')])
Vizro().build(vm.Dashboard(pages=[page])).run(port=8090)
```
- === "Result"
- [![VizroDashboard]][VizroDashboard]
-
- [VizroDashboard]: ../../assets/user_guides/chart_into_dashboard_large.png
+ === "Result"
+ [![VizroDashboard]][vizrodashboard]
## Use Vizro-AI dynamically to return a `fig` object
-We can also use Vizro-AI dynamically and assign the output of `plot()` directly to the fig variable, enabling its reuse in the `vm.Graph.figure` argument.
-This method offers streamlined efficiency, eliminating the need for code copying.
-Note that each dashboard run triggers an API call to the LLM, possibly escalating costs. This can be avoided if the `fig` object is stored and retrieved as needed, instead of making repeated calls to `plot()`.
+We can also use Vizro-AI dynamically and assign the output of `plot()` directly to the fig variable, enabling its reuse in the `vm.Graph.figure` argument. This method offers streamlined efficiency, eliminating the need for code copying. Note that each dashboard run triggers an API call to the LLM, possibly escalating costs. This can be avoided if the `fig` object is stored and retrieved as needed, instead of making repeated calls to `plot()`.
Executing the code below yields the identical dashboard as the example above.
-
!!! example "Use Vizro-AI fig directly in vizro dashboard"
=== "Code for the cell"
-
```py hl_lines="13-18 23"
from vizro import Vizro
import vizro.models as vm
@@ -143,28 +136,33 @@ Executing the code below yields the identical dashboard as the example above.
vizro_ai = VizroAI(model="gpt-4o")
fig = vizro_ai.plot(df,
- """Plot a bubble chart to show the changes in life expectancy
- and GDP per capita for each country over time.
- Color the bubbles by continent.
- Add animation on yearly basis, and do not use facets.
- Put the legend on top""")
+ """Plot a bubble chart to show the changes in life expectancy
+ and GDP per capita for each country over time.
+ Color the bubbles by continent.
+ Add animation on yearly basis, and do not use facets.
+ Put the legend on top"""
+ )
page = vm.Page(
title = 'Demographics',
components = [
vm.Graph(figure=fig),
- vm.Graph(figure = px.box(df,
- x='continent',
- y='lifeExp',
- color='continent',
- title='Life Expectancy per Continent'))],
+ vm.Graph(
+ figure=px.box(
+ df, x='continent', y='lifeExp', color='continent', title='Life Expectancy per Continent'
+ )
+ )
+ ],
controls = [
vm.Filter(column='country'),
vm.Filter(column='continent')])
Vizro().build(vm.Dashboard(pages=[page])).run(port=8090)
```
+
=== "Result"
- [![VizroDashboard2]][VizroDashboard2]
+ [![VizroDashboard2]][vizrodashboard2]
- [VizroDashboard2]: ../../assets/user_guides/chart_into_dashboard_large.png
+[vizroaichart]: ../../assets/user_guides/vizro-ai-chart.png
+[vizrodashboard]: ../../assets/user_guides/chart_into_dashboard_large.png
+[vizrodashboard2]: ../../assets/user_guides/chart_into_dashboard_large.png
diff --git a/vizro-ai/docs/pages/user-guides/advanced-options.md b/vizro-ai/docs/pages/user-guides/advanced-options.md
index 528a74912..4d63eaa35 100644
--- a/vizro-ai/docs/pages/user-guides/advanced-options.md
+++ b/vizro-ai/docs/pages/user-guides/advanced-options.md
@@ -4,19 +4,20 @@ This guide shows you how to use the advanced options of `VizroAI.plot`.
First we show how to change the input parameters of the function, as follows:
-* control over whether code gets executed,
-* the number of retries of `.plot` when it fails validation,
-* how to request a comprehensive output (when `return_elements=True`).
+- control over whether code gets executed,
+- the number of retries of `.plot` when it fails validation,
+- how to request a comprehensive output (when `return_elements=True`).
Second we show how to use this more comprehensive output, enabling control of code generation and `fig` object production.
## Inputs of `VizroAI.plot`
### `user_input`
-This is the natural language query from which, together with a data sample, the LLM creates a plotly chart. For the query, you can [use English or a different language](use-different-languages.md). The complexity of the resulting chart [depends on the vendor model capabilities](customize-vizro-ai.md#what-model-to-choose).
+This is the natural language query from which, together with a data sample, the LLM creates a plotly chart. For the query, you can [use English or a different language](use-different-languages.md). The complexity of the resulting chart [depends on the vendor model capabilities](customize-vizro-ai.md#what-model-to-choose).
### `df`
+
Supply any `pandas` data frame to base your query on. The LLM will receive a sample of this data frame to form an appropriate graph.
If the option `validate_code` is set to `True` (which it is by default), the LLM created chart code will be evaluated on a sample of this data frame.
@@ -24,10 +25,13 @@ If the option `validate_code` is set to `True` (which it is by default), the LLM
If `return_elements` is set to `False`, then the returned `fig` object will be created based on this (entire) data frame.
+
### `max_debug_retry`
+
This number determines how often the tool will try to correct an incorrect response (that fails various validation criteria). Under the hood this is [implemented via pydantic validators](https://docs.pydantic.dev/1.10/usage/validators/). The last response will be re-sent to the LLM together with the validation error(s) in order to receive an improved response. This concept is [inspired by the amazing instructor library](https://github.com/jxnl/instructor).
### `return_elements`
+
This boolean (by default `False`) determines the return type of `VizroAI.plot`.
If set to `False`, then dynamically generated Python code is executed to produce a `plotly.graph_objects.Figure` object from the LLM response and the user supplied data frame. Strictly speaking, it produces a `vizro.charts._charts_utils._DashboardReadyFigure`, which behaves essentially like the former, but is ready to be [inserted](add-generated-chart-usecase.md) into a [Vizro](https://vizro.readthedocs.io/en/stable/) dashboard. It also comes with the default Vizro dark theme.
@@ -35,8 +39,11 @@ If set to `False`, then dynamically generated Python code is executed to produce
If set to `True`, a class (pydantic model) is returned from which the `fig` object, but also various other outputs can be generated. (see below)
### `validate_code`
+
This boolean (by default `True`) determines whether the LLM generated Python code executes with a sample of the data in order to verify that it runs and produces a plotly figure. Be sure [to read and understand what it means when dynamically generated code is executed](../explanation/safety-in-vizro-ai.md#execution-of-dynamic-code-in-vizro-ai).
+
+
If `return_elements=True` **and** `validate_code=False`, then no code is executed to obtain the return of `VizroAI.plot`. This means that the code string obtained is not validated, but also that no code was executed.
## Output if `return_elements=True`
@@ -44,10 +51,10 @@ If `return_elements=True` **and** `validate_code=False`, then no code is execute
If `return_elements=True`, then instead of a `fig` object, a class is returned, which enables the following options:
### Obtain `vizro` code string
+
You can obtain the code string that would produce the answer to the user query as a Vizro dashboard ready figure as follows. The name for the function will be `custom_chart`:
!!! example "Vizro code"
-
=== "Code"
```py
from vizro_ai import VizroAI
@@ -76,10 +83,10 @@ You can obtain the code string that would produce the answer to the user query a
```
### Obtain `plotly` code string
+
You can obtain the code string that would produce the answer to the user query as a pure `plotly.graph_objects.Figure` as follows. The name for the function will be `custom_chart`:
!!! example "Plotly code"
-
=== "Code"
```py
from vizro_ai import VizroAI
@@ -110,10 +117,10 @@ You can obtain the code string that would produce the answer to the user query a
You can create the `fig` object using either of the above produced code strings (vizro or plotly), changing the chart name, and using different data. Note that when executing this function, the produced code string will be dynamically executed. Be sure [to read and understand what it means when dynamically generated code is executed](../explanation/safety-in-vizro-ai.md#execution-of-dynamic-code-in-vizro-ai).
#### Vizro ready
+
This `fig` object is in the standard `vizro_dark` theme, and can [be inserted into a Vizro dashboard](add-generated-chart-usecase.md).
!!! example "Vizro `fig` object"
-
=== "Code"
```py
from vizro_ai import VizroAI
@@ -128,15 +135,13 @@ This `fig` object is in the standard `vizro_dark` theme, and can [be inserted in
```
=== "Result"
- [![VizroAIChartVizro]][VizroAIChartVizro]
- ```
- [VizroAIChartVizro]: ../../assets/user_guides/VizroAIVizro.png
+ [![VizroAIChartVizro]][vizroaichartvizro]
#### Pure Plotly/Dash
+
This `fig` object is a basic plotly figure.
!!! example "Plotly `fig` object"
-
=== "Code"
```py
from vizro_ai import VizroAI
@@ -151,19 +156,18 @@ This `fig` object is a basic plotly figure.
```
=== "Result"
- [![VizroAIChartPlotly]][VizroAIChartPlotly]
- ```
- [VizroAIChartPlotly]: ../../assets/user_guides/VizroAIPlotly.png
+ [![VizroAIChartPlotly]][vizroaichartplotly]
#### Using different data
+
+
You can create the `fig` object with different data while ensuring the overall schema remains consistent. You can re-evaluate this function to generate various `fig` objects for different data. For example, the code could be generated using fake or sample data fed into Vizro-AI. When moving to production, you can switch the data source to the complete dataset, as long as the data schema is consistent.
+
!!! example "Different data"
-
=== "Code"
-
```py
from vizro_ai import VizroAI
import plotly.express as px
@@ -180,19 +184,14 @@ You can create the `fig` object with different data while ensuring the overall s
```
=== "Result"
- [![VizroAINewData]][VizroAINewData]
- ```
- [VizroAINewData]: ../../assets/user_guides/VizroAINewData.png
- ```
+ [![VizroAINewData]][vizroainewdata]
#### Changing the chart name
-This option executes the chart code with the name given under `chart_name`. This can be important when you want to avoid overwriting variables in the namespace.
+This option executes the chart code with the name given under `chart_name`. This can be important when you want to avoid overwriting variables in the namespace.
!!! example "Changing the `chart_name`"
-
=== "Code"
-
```py
from vizro_ai import VizroAI
import plotly.express as px
@@ -209,3 +208,7 @@ This option executes the chart code with the name given under `chart_name`. This
```py
-[](https://pypi.org/project/vizro/)
-[](https://badge.fury.io/py/vizro)
-[](https://github.com/mckinsey/vizro/blob/main/LICENSE.md)
-[](https://vizro.readthedocs.io/)
-[](https://www.bestpractices.dev/projects/7858)
+[](https://pypi.org/project/vizro/) [](https://badge.fury.io/py/vizro) [](https://github.com/mckinsey/vizro/blob/main/LICENSE.md) [](https://vizro.readthedocs.io/) [](https://www.bestpractices.dev/projects/7858)
-Documentation |
-Get Started |
-Vizro examples gallery
+Documentation | Get Started | Vizro examples gallery
@@ -100,9 +94,7 @@ You can see Vizro in action by clicking on the following image or by visiting [t
## Visual vocabulary
-Our visual vocabulary dashboard helps you to select and create various types of charts. It helps you decide when to use
-each chart type, and offers sample Python code to create these charts with [Plotly](https://plotly.com/python/) and
-embed them into a Vizro dashboard.
+Our visual vocabulary dashboard helps you to select and create various types of charts. It helps you decide when to use each chart type, and offers sample Python code to create these charts with [Plotly](https://plotly.com/python/) and embed them into a Vizro dashboard.
@@ -138,8 +130,7 @@ We encourage you to ask and answer technical questions via the [GitHub Issues](h
## Contributing
-To learn more about making a contribution,
-please see the [contributing guide](https://vizro.readthedocs.io/en/stable/pages/development/contributing/) for more information
+To learn more about making a contribution, please see the [contributing guide](https://vizro.readthedocs.io/en/stable/pages/development/contributing/) for more information
You can also view current and former [contributors](https://vizro.readthedocs.io/en/stable/pages/development/authors/)
diff --git a/vizro-core/changelog.d/20241202_150655_huong_li_nguyen_refactor_bs_example.md b/vizro-core/changelog.d/20241202_150655_huong_li_nguyen_refactor_bs_example.md
index 7c0d58d4f..4abc0f11e 100644
--- a/vizro-core/changelog.d/20241202_150655_huong_li_nguyen_refactor_bs_example.md
+++ b/vizro-core/changelog.d/20241202_150655_huong_li_nguyen_refactor_bs_example.md
@@ -10,36 +10,42 @@ Uncomment the section that is right (remove the HTML comment wrapper).
- 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))
-->
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/vizro-core/changelog.d/20241203_145221_antony.milne_mdformat.md b/vizro-core/changelog.d/20241203_145221_antony.milne_mdformat.md
new file mode 100644
index 000000000..4abc0f11e
--- /dev/null
+++ b/vizro-core/changelog.d/20241203_145221_antony.milne_mdformat.md
@@ -0,0 +1,54 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/vizro-core/changelog.d/20241203_150134_antony.milne_mdformat.md b/vizro-core/changelog.d/20241203_150134_antony.milne_mdformat.md
new file mode 100644
index 000000000..4abc0f11e
--- /dev/null
+++ b/vizro-core/changelog.d/20241203_150134_antony.milne_mdformat.md
@@ -0,0 +1,54 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/vizro-core/docs/index.md b/vizro-core/docs/index.md
index 1cc99a4ce..e9886376b 100644
--- a/vizro-core/docs/index.md
+++ b/vizro-core/docs/index.md
@@ -4,58 +4,56 @@ Vizro is a toolkit for creating modular data visualization applications.
-- :fontawesome-solid-forward-fast:{ .lg .middle } __New to Vizro?__
+- :fontawesome-solid-forward-fast:{ .lg .middle } __New to Vizro?__
---
- [:octicons-arrow-right-24: Quickstart tutorial](pages/tutorials/first-dashboard.md)
+ [:octicons-arrow-right-24: Quickstart tutorial](pages/tutorials/first-dashboard.md)
+
[:octicons-arrow-right-24: Install Vizro](pages/user-guides/install.md)
+- :fontawesome-solid-keyboard:{ .lg .middle } __Vizro features__
+ ---
+ [:octicons-arrow-right-24: Fundamentals](pages/user-guides/dashboard.md)
-- :fontawesome-solid-keyboard:{ .lg .middle } __Vizro features__
+ [:octicons-arrow-right-24: Components overview](pages/user-guides/components.md)
- ---
+ [:octicons-arrow-right-24: Filters, parameters and selectors](pages/user-guides/filters.md)
- [:octicons-arrow-right-24: Fundamentals](pages/user-guides/dashboard.md)
- [:octicons-arrow-right-24: Components overview](pages/user-guides/components.md)
- [:octicons-arrow-right-24: Filters, parameters and selectors](pages/user-guides/filters.md)
[:octicons-arrow-right-24: Visual formatting](pages/user-guides/visual-formatting.md)
-
-
-- :fontawesome-solid-microscope:{ .lg .middle } __Hands-on code__
+- :fontawesome-solid-microscope:{ .lg .middle } __Hands-on code__
---
- [:octicons-arrow-right-24: Tutorials](pages/tutorials/explore-components.md)
- [:octicons-arrow-right-24: Examples](https://vizro.mckinsey.com) - + [:octicons-arrow-right-24: Tutorials](pages/tutorials/explore-components.md) + [:octicons-arrow-right-24: Examples](https://vizro.mckinsey.com) -- :material-scale-balance:{ .lg .middle } __FAQs__ +- :material-scale-balance:{ .lg .middle } __FAQs__ --- - [:octicons-arrow-right-24: How is Vizro different to Streamlit?](pages/explanation/faq.md/#how-does-vizro-differ-from-dash-or-streamlit)
- [:octicons-arrow-right-24: Where can I ask a question about Vizo?](pages/explanation/faq.md/#i-still-have-a-question-where-can-i-ask-it)
- [:octicons-arrow-right-24: Other FAQs](pages/explanation/faq.md)
+ [:octicons-arrow-right-24: How is Vizro different to Streamlit?](pages/explanation/faq.md/#how-does-vizro-differ-from-dash-or-streamlit) + [:octicons-arrow-right-24: Where can I ask a question?](pages/explanation/faq.md/#i-still-have-a-question-where-can-i-ask-it) + [:octicons-arrow-right-24: Other FAQs](pages/explanation/faq.md) -- :fontawesome-solid-hands-holding-circle:{ .lg .middle } __Get involved__ +- :fontawesome-solid-hands-holding-circle:{ .lg .middle } __Get involved__ --- - [:octicons-arrow-right-24: Contribute code](pages/explanation/contributing.md)
+ [:octicons-arrow-right-24: Contribute code](pages/explanation/contributing.md) + [:octicons-arrow-right-24: Contribute to our docs](pages/explanation/documentation-style-guide.md) -- :fontawesome-solid-chart-column:{ .lg .middle } __Vizro-AI__ +- :fontawesome-solid-chart-column:{ .lg .middle } __Vizro-AI__ --- [:octicons-arrow-right-24: Vizro-AI: Use natural language queries to build Plotly charts](https://vizro.readthedocs.io/projects/vizro-ai/) -
diff --git a/vizro-core/docs/pages/explanation/authors.md b/vizro-core/docs/pages/explanation/authors.md
index e684197e5..d88f73ea6 100644
--- a/vizro-core/docs/pages/explanation/authors.md
+++ b/vizro-core/docs/pages/explanation/authors.md
@@ -1,27 +1,21 @@
## Current team members
+
-[Alexey Snigir](https://github.com/l0uden),
-[Antony Milne](https://github.com/antonymilne),
-[Dan Dumitriu](https://github.com/dandumitriu1),
-[Huong Li Nguyen](https://github.com/huong-li-nguyen),
-[Jo Stichbury](https://github.com/stichbury),
-[Joseph Perkins](https://github.com/Joseph-Perkins),
-[Lingyi Zhang](https://github.com/lingyielia),
-[Maximilian Schulz](https://github.com/maxschulz-COL),
-[Nadija Graca](https://github.com/nadijagraca), and
-[Petar Pejovic](https://github.com/petar-qb)
-
+[Alexey Snigir](https://github.com/l0uden), [Antony Milne](https://github.com/antonymilne), [Dan Dumitriu](https://github.com/dandumitriu1), [Huong Li Nguyen](https://github.com/huong-li-nguyen), [Jo Stichbury](https://github.com/stichbury), [Joseph Perkins](https://github.com/Joseph-Perkins), [Lingyi Zhang](https://github.com/lingyielia), [Maximilian Schulz](https://github.com/maxschulz-COL), [Nadija Graca](https://github.com/nadijagraca), and [Petar Pejovic](https://github.com/petar-qb)
+
+
## Previous team members and code contributors
+
-[Ann Marie Ward](https://github.com/AnnMarieW), [Anna Xiong](https://github.com/Anna-Xiong), [Annie Wachsmuth](https://github.com/anniecwa), [ataraexia](https://github.com/ataraexia), [axa99](https://github.com/axa99), [Bhavana Sundar](https://github.com/bhavanaeh), [Bo Xu](https://github.com/boxuboxu), [Chiara Pullem](https://github.com/chiara-sophie), [Denis Lebedev](https://github.com/DenisLebedevMcK), [Elena Fridman](https://github.com/EllenWie), [Ferida Mohammed](https://github.com/feridaaa), [Hamza Oza](https://github.com/hamzaoza), [Hansaem Park](https://github.com/sammitako), [Hilary Ivy](https://github.com/hxe00570), [Jasmine Wu](https://github.com/jazwu), [Jenelle Yonkman](https://github.com/yonkmanjl), [Jingjing Guo](https://github.com/jjguo-mck), [Juan Luis Cano Rodríguez](https://github.com/astrojuanlu), [Kee Wen Ng](https://github.com/KeeWenNgQB), [Leon Nallamuthu](https://github.com/leonnallamuthu), [Lydia Pitts](https://github.com/LydiaPitts), [Ned Letcher](https://github.com/ned2), [Nikolaos Tsaousis](https://github.com/tsanikgr), [njmcgrat](https://github.com/njmcgrat), [Oleksandr Serdiuk](https://github.com/oserdiuk-lohika), [Prateek Bajaj](https://github.com/prateekdev552), [Qiuyi Chen](https://github.com/Qiuyi-Chen), [Rashida Kanchwala](https://github.com/rashidakanchwala), [Riley Dou](https://github.com/rilieo), [Rosheen C.](https://github.com/rc678), [Sylvie Zhang](https://github.com/sylviezhang37), and [Upekesha Ngugi](https://github.com/upekesha).
+[Ann Marie Ward](https://github.com/AnnMarieW), [Anna Xiong](https://github.com/Anna-Xiong), [Annie Wachsmuth](https://github.com/anniecwa), [ataraexia](https://github.com/ataraexia), [axa99](https://github.com/axa99), [Bhavana Sundar](https://github.com/bhavanaeh), [Bo Xu](https://github.com/boxuboxu), [Chiara Pullem](https://github.com/chiara-sophie), [Denis Lebedev](https://github.com/DenisLebedevMcK), [Elena Fridman](https://github.com/EllenWie), [Ferida Mohammed](https://github.com/feridaaa), [Hamza Oza](https://github.com/hamzaoza), [Hansaem Park](https://github.com/sammitako), [Hilary Ivy](https://github.com/hxe00570), [Jasmine Wu](https://github.com/jazwu), [Jenelle Yonkman](https://github.com/yonkmanjl), [Jingjing Guo](https://github.com/jjguo-mck), [Juan Luis Cano Rodríguez](https://github.com/astrojuanlu), [Kee Wen Ng](https://github.com/KeeWenNgQB), [Leon Nallamuthu](https://github.com/leonnallamuthu), [Lydia Pitts](https://github.com/LydiaPitts), [Ned Letcher](https://github.com/ned2), [Nikolaos Tsaousis](https://github.com/tsanikgr), [njmcgrat](https://github.com/njmcgrat), [Oleksandr Serdiuk](https://github.com/oserdiuk-lohika), [Prateek Bajaj](https://github.com/prateekdev552), [Qiuyi Chen](https://github.com/Qiuyi-Chen), [Rashida Kanchwala](https://github.com/rashidakanchwala), [Riley Dou](https://github.com/rilieo), [Rosheen C.](https://github.com/rc678), [Sylvie Zhang](https://github.com/sylviezhang37), and [Upekesha Ngugi](https://github.com/upekesha).
with thanks to Sam Bourton and Kevin Staight for sponsorship, inspiration and guidance,
-and special thanks to
-[Wesley Leong](https://github.com/wesleyleong), [Jonas Kemper](https://github.com/jonasrk) and team for origination and support
+and special thanks to [Wesley Leong](https://github.com/wesleyleong), [Jonas Kemper](https://github.com/jonasrk) and team for origination and support
(plus everyone else who helped to test, guide, support and encourage development)
+
diff --git a/vizro-core/docs/pages/explanation/contributing.md b/vizro-core/docs/pages/explanation/contributing.md
index 7e532ae3b..bf71bfb39 100644
--- a/vizro-core/docs/pages/explanation/contributing.md
+++ b/vizro-core/docs/pages/explanation/contributing.md
@@ -4,22 +4,20 @@ Contributions of all experience levels are welcome! There are many ways to contr
Our development follows a standard [GitHub flow](https://docs.github.com/en/get-started/using-github/github-flow). To be merged, your PR must meet all the following requirements:
-* two approving reviews (including a code owner)
-* Continuous Integration (CI) checks pass
-* code is up-to-date with `main`
+- two approving reviews (including a code owner)
+- Continuous Integration (CI) checks pass
+- code is up-to-date with `main`
If you are a first-time contributor with a new GitHub account then you may also need to [wait for CI workflows to be approved](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/approving-workflow-runs-from-public-forks).
We aim to make the contribution process as easy as possible by having only one direct development dependency: [Hatch](https://hatch.pypa.io/). There are two ways to develop on Vizro:
-* [GitHub Codespaces](https://docs.github.com/en/codespaces). This is the recommended method if you are a new contributor. It is the quickest and easiest way to get started. All development can be done in your browser in a temporary environment; you do not need to set up anything on your computer. The [Develop on GitHub Codespaces](#develop-on-github-codespaces) section has full instructions on how to do this.
-* Local machine. If you are more experienced then you might prefer to develop on your own computer. The [Develop locally](#develop-locally) section has full instructions on how to do this.
+- [GitHub Codespaces](https://docs.github.com/en/codespaces). This is the recommended method if you are a new contributor. It is the quickest and easiest way to get started. All development can be done in your browser in a temporary environment; you do not need to set up anything on your computer. The [Develop on GitHub Codespaces](#develop-on-github-codespaces) section has full instructions on how to do this.
+- Local machine. If you are more experienced then you might prefer to develop on your own computer. The [Develop locally](#develop-locally) section has full instructions on how to do this.
!!! note
-
For either method, Hatch is the _only development dependency_. You do not need to manually install Python or create any virtual environments to develop Vizro; all this will be handled for you behind the scenes by Hatch. We have also configured our codespace to pre-install Hatch. If you develop on GitHub Codespaces you don't need to install anything at all!
-
## Develop on GitHub Codespaces
There is no need to manually create a fork of the Vizro code if you use GitHub Codespaces. A fork is [automatically created for you](https://docs.github.com/en/codespaces/developing-in-a-codespace/using-source-control-in-your-codespace#about-automatic-forking).
@@ -27,17 +25,17 @@ There is no need to manually create a fork of the Vizro code if you use GitHub C
To develop on [GitHub Codespaces](https://docs.github.com/en/codespaces), follow the below steps:
1. [Create a codespace for our repository](https://codespaces.new/mckinsey/vizro). Leave the settings on their defaults and click "Create codespace" to start your codespace. It should take 1-2 minutes to fully launch and automatically start an example dashboard on port 8050. In the rare event that the codespace fails to start correctly and enters recovery mode, you should [rebuild the container](https://docs.github.com/en/codespaces/developing-in-a-codespace/rebuilding-the-container-in-a-codespace#rebuilding-a-container) or start a whole new codespace.
-2. Make changes to Vizro code in your codespace. See the [GitHub Codespaces documentation on developing in a codespace](https://docs.github.com/en/codespaces/developing-in-a-codespace/developing-in-a-codespace) for more information.
-3. Add your name to the [list of contributors](authors.md) (source file `vizro-core/docs/pages/explanation/authors.md`).
-4. [Create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork).
+1. Make changes to Vizro code in your codespace. See the [GitHub Codespaces documentation on developing in a codespace](https://docs.github.com/en/codespaces/developing-in-a-codespace/developing-in-a-codespace) for more information.
+1. Add your name to the [list of contributors](authors.md) (source file `vizro-core/docs/pages/explanation/authors.md`).
+1. [Create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork).
## Develop locally
1. Install Hatch. There are [several ways to do this](https://hatch.pypa.io/latest/install/).
-2. [Fork the Vizro repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) and clone it to your local machine.
-3. Make changes to Vizro code in your fork.
-4. Add your name to the [list of contributors](authors.md) (source file `vizro-core/docs/pages/explanation/authors.md`).
-5. [Create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork).
+1. [Fork the Vizro repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) and clone it to your local machine.
+1. Make changes to Vizro code in your fork.
+1. Add your name to the [list of contributors](authors.md) (source file `vizro-core/docs/pages/explanation/authors.md`).
+1. [Create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork).
## How to use Hatch
@@ -45,16 +43,18 @@ Regardless of whether you are developing locally or in a codespace, everything y
The Hatch commands you need most commonly are as follows. These must be executed with `vizro-core` as your current working directory:
-* [`hatch run pypath`](#hatch-run-pypath) shows the path to the Python interpreter.
-* [`hatch run example`](#hatch-run-example) runs an example dashboard on port 8050 that hot-reloads while you edit it. On GitHub Codespaces, this runs automatically on startup.
-* [`hatch run lint`](#hatch-run-lint) checks and fixes code quality and formatting. This is included in CI checks.
-* [`hatch run changelog:add`](#hatch-run-changelogadd) generates a new changelog fragment. Changelog inclusion is checked by CI and required for all changes to source code.
-* [`hatch run test-unit`](#hatch-run-test-unit) runs the test suite. This is included in CI checks.
-* [`hatch run docs:serve`](#hatch-run-docsserve) builds and displays documentation that hot-reloads while you edit it. Documentation is also built automatically in your PR and can be previewed on Read The Docs.
-* [`hatch run pip`](#hatch-run-pip) provides a [pip-compatible interface using uv](https://docs.astral.sh/uv/pip/). You should not need to use this much.
+- [`hatch run pypath`](#hatch-run-pypath) shows the path to the Python interpreter.
+- [`hatch run example`](#hatch-run-example) runs an example dashboard on port 8050 that hot-reloads while you edit it. On GitHub Codespaces, this runs automatically on startup.
+- [`hatch run lint`](#hatch-run-lint) checks and fixes code quality and formatting. This is included in CI checks.
+- [`hatch run changelog:add`](#hatch-run-changelogadd) generates a new changelog fragment. Changelog inclusion is checked by CI and required for all changes to source code.
+- [`hatch run test-unit`](#hatch-run-test-unit) runs the test suite. This is included in CI checks.
+- [`hatch run docs:serve`](#hatch-run-docsserve) builds and displays documentation that hot-reloads while you edit it. Documentation is also built automatically in your PR and can be previewed on Read The Docs.
+- [`hatch run pip`](#hatch-run-pip) provides a [pip-compatible interface using uv](https://docs.astral.sh/uv/pip/). You should not need to use this much.
+
To save yourself from repeatedly typing `hatch run` you might like to [set up an alias](https://www.tecmint.com/create-alias-in-linux/):
+
```console
@@ -67,10 +67,10 @@ This enables you to run, for example, `hr lint` instead of `hatch run lint`. On
`hatch run pypath` shows the path to the Python interpreter. This is useful for setting a Python interpreter in your IDE to navigate the codebase. For example, in GitHub Codespaces and VS Code:
-* Run `hatch run pypath` and copy the output to your clipboard.
-* Open the Command Palette (++ctrl+shift+p++).
-* Run the "Python: Select Interpreter" command and select the "Enter interpreter path..." option.
-* Paste the path.
+- Run `hatch run pypath` and copy the output to your clipboard.
+- Open the Command Palette (++ctrl+shift+p++).
+- Run the "Python: Select Interpreter" command and select the "Enter interpreter path..." option.
+- Paste the path.
### `hatch run example`
@@ -82,16 +82,15 @@ You can run any example in `vizro-core/examples` or its subdirectories by runnin
Examples are run with the following settings:
-* [Dash dev tools](https://dash.plotly.com/devtools) enabled. This includes hot reloading, so that any changes to the example app or Vizro source code should automatically show in your dashboard without needing refresh or restart anything.
-* The environment variable `VIZRO_LOG_LEVEL = "DEBUG"` to show log messages of level `DEBUG` and above.
+- [Dash dev tools](https://dash.plotly.com/devtools) enabled. This includes hot reloading, so that any changes to the example app or Vizro source code should automatically show in your dashboard without needing refresh or restart anything.
+- The environment variable `VIZRO_LOG_LEVEL = "DEBUG"` to show log messages of level `DEBUG` and above.
### `hatch run lint`
`hatch run lint` checks and fixes code quality and formatting. This is included in CI checks. All linting and associated dependencies are controlled by [pre-commit](https://pre-commit.com/) hooks. We use the [pre-commit.ci](https://pre-commit.ci/) to automatically fix all the linting checks that we can when a PR is pushed. Other linting failures (such as `mypy`) need manual intervention from the developer.
!!! note
-
- The first time you run `hatch run lint` it may take a couple of minutes, since pre-commit needs to setup linting environments. Subsequent runs reuse these environments and are much faster.
+ The first time you run `hatch run lint` it may take a couple of minutes, since pre-commit needs to setup linting environments. Further runs reuse these environments and are much faster.
`hatch run lint` runs the pre-commit hooks on all (not only staged) files. You can run an individual hook, for example `mypy`, on all files by running `hatch run lint mypy`.
@@ -106,8 +105,7 @@ The format of our changelog is based on [Keep a Changelog](https://keepachangelo
Run `hatch run changelog:add` to create a changelog fragment and then uncomment the relevant section(s). If you are uncertain about what to add or whether to add anything at all, refer to [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). The rule of thumb is that if Vizro users would be affected in any way then the changes should be described in the changelog.
!!! note
-
- Changes that do not affect source code do not need a changelog fragment. This facilitates simple modifications to documentation [made directly on GitHub](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files) or with the [github.dev](https://docs.github.com/en/codespaces/the-githubdev-web-based-editor), where no terminal is available to run `hatch changelog:add`. Any changes to source code require a changelog fragment to be generated. If your changes do not require a changelog entry then you still need to generate the fragment but can leave it all commented out.
+ Changes that do not affect source code do not need a changelog fragment. This simplifies modifications to documentation [made directly on GitHub](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files) or within the [github.dev](https://docs.github.com/en/codespaces/the-githubdev-web-based-editor), where no terminal is available to run `hatch changelog:add`. Any changes to source code require a changelog fragment to be generated. If your changes do not require a changelog entry then you still need to generate the fragment but can leave it all commented out.
### `hatch run test-unit`
@@ -127,9 +125,9 @@ hatch run all.py3.10:test-unit-coverage
In addition to running unit tests with code coverage, CI also performs the following checks:
-* `hatch run test-integration` runs integration tests that include checking that the example apps in `vizro-core/examples` run.
-* `hatch run test-js` runs Javascript tests using [jest](https://jestjs.io/). Arguments are passed through to the underlying `npx jest` command, for example `hatch run test-js --help`.
-* QA tests. These are run on a separate private `vizro-qa` repository and not triggered by PRs coming from forks.
+- `hatch run test-integration` runs integration tests that include checking that the example apps in `vizro-core/examples` run.
+- `hatch run test-js` runs Javascript tests using [jest](https://jestjs.io/). Arguments are passed through to the underlying `npx jest` command, for example `hatch run test-js --help`.
+- QA tests. These are run on a separate private `vizro-qa` repository and not triggered by PRs coming from forks.
### `hatch run docs:serve`
@@ -146,7 +144,6 @@ Vizro's dependencies are described by the `dependencies` section in `vizro-core/
We have [configured Hatch to use uv](https://hatch.pypa.io/1.12/how-to/environment/select-installer/) for rapid virtual environment creation, dependency resolution and installation.
!!! note
-
If you have installed unwanted dependencies in your Hatch environment then the simplest solution is to delete the environment (`hatch env remove` to remove one environment or `hatch env prune` to remove all environments). Your next `hatch run` command will recreate the environment and install all the dependencies it needs.
If for some reason you do need to use `pip` then the correct way to do so is through `hatch run pip`. For example, you could run `hatch run pip show plotly`. This will use the version of uv that Hatch itself uses under the hood. If you already have uv installed globally then `uv pip show plotly` would also work.
diff --git a/vizro-core/docs/pages/explanation/documentation-style-guide.md b/vizro-core/docs/pages/explanation/documentation-style-guide.md
index 9c397754e..40f989ac0 100644
--- a/vizro-core/docs/pages/explanation/documentation-style-guide.md
+++ b/vizro-core/docs/pages/explanation/documentation-style-guide.md
@@ -14,8 +14,8 @@ The names of our products are **Vizro** and **Vizro-AI**.
We refer to other products using their preferred capitalization. For example:
-* Dash and Pydantic are always capitalized, except where given as Python package names `dash` and `pydantic`.
-* pandas DataFrame has a lowercase "p" and camelcase "DataFrame".
+- Dash and Pydantic are always capitalized, except where given as Python package names `dash` and `pydantic`.
+- pandas DataFrame has a lowercase "p" and camelcase "DataFrame".
Vizro components are named using lower case:
@@ -28,46 +28,42 @@ Use code font when referring to the component as a class or object:
Avoid referring to data using terms like "dataset" or "connector". Prefer to use just "data" or, where that does not feel natural, "data source".
## Bullets
-* Capitalize the first word, and end the bullet with a period.
-* Don't use numbered bullets except for a sequence of instructions, or where you have to refer back to one of them in the text (or a diagram).
+
+- Capitalize the first word, and end the bullet with a period.
+- Don't use numbered bullets except for a sequence of instructions, or where you have to refer back to one of them in the text (or a diagram).
## Call out boxes
Keep the amount of text, and the number and variety of callouts used, to a minimum. There is a [broad set available](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types) for use in the Vizro docs, but we limit usage to notes, warnings, details and examples:
!!! note "note"
-
- For notable information.
+ For notable information.
!!! warning "warning"
-
- To indicate a potential gotcha.
+ To indicate a potential gotcha.
??? details "See more details"
-
A side note (used sparingly)
!!! example "example"
-
- For example code.
-
+ For example code.
Callout boxes can be made collapsible: if you use them, add them to the page so they are initially collapsed.
???+ note "Limit the use of collapsible callouts to secondary information only"
-
Don't use expanded-on-load collapsibles like this one. If the callout contains important information and needs to be shown as expanded on page load, it should simply be non-collapsible.
## Capitalization
-* Only capitalize proper nouns such as the names of technology products, other tools and services.
-* Don't capitalize cloud, internet, machine learning, or advanced analytics. Take a look at the [Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/accessibility-terms) if you're unsure.
-* Follow sentence case, which capitalizes only the first word of a title/subtitle. We prefer "An introduction to data visualization" to "An Introduction to Data Visualization".
+- Only capitalize proper nouns such as the names of technology products, other tools and services.
+- Don't capitalize cloud, internet, machine learning, or advanced analytics. Take a look at the [Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/accessibility-terms) if you're unsure.
+- Follow sentence case, which capitalizes only the first word of a title/subtitle. We prefer "An introduction to data visualization" to "An Introduction to Data Visualization".
## Code formatting
-* Mark code blocks with the appropriate language to enable syntax highlighting.
-* We use a `bash` lexer for all codeblocks that represent the terminal, and we don't include the prompt.
-* Use the code format for Python package names such as `pandas` or `pydantic`.
+
+- Mark code blocks with the appropriate language to enable syntax highlighting.
+- We use a `bash` lexer for all codeblocks that represent the terminal, and we don't include the prompt.
+- Use the code format for Python package names such as `pandas` or `pydantic`.
## Headings and subheadings
@@ -77,43 +73,45 @@ Aim to avoid use of gerunds (verb+ing) where you can. So your page should be "Ge
In Vizro, when you are working on a how-to guide, there are a few additional guidelines to follow for consistency:
-* Don't use "how to" in the file name: keep that as short as possible.
-* The title (H1 header) should start with "How to".
-* Don't use "how to" in the subsections that follow (H2 - H5) unless you consider the alternative to be confusing.
-* Don't use gerund form in the subsections either.
+- Don't use "how to" in the file name: keep that as short as possible.
+- The title (H1 header) should start with "How to".
+- Don't use "how to" in the subsections that follow (H2 - H5) unless you consider the alternative to be confusing.
+- Don't use gerund form in the subsections either.
Example: In a page called "Filters" you would have the following:
-* H1: "How to use filters"
-* H2 subsection: "Use a custom filter" and not "How to use a custom filter" nor "Using a custom filter".
-
+- H1: "How to use filters"
+- H2 subsection: "Use a custom filter" and not "How to use a custom filter" nor "Using a custom filter".
## Instructions
Prefer to use imperatives to make instructions. For example:
+
> Complete the configuration steps
You don't need to use the word "please" -- readers want less to read and don't think it's rude if you omit it.
You can also use second person:
+
> You should complete the configuration steps.
Don't use the passive tense:
-> The configuration steps should be completed.
-!!!note "What is passive tense?"
+> The configuration steps should be completed.
+!!! note "What is passive tense?"
If you can add "by zombies" to the end of any sentence, it is passive.
- * For example: "The configuration steps should be completed." can also be read as: "The configuration should be completed BY ZOMBIES".
- * Instead, you'd write this: "You should complete the configuration steps" or better still, "Complete the configuration steps".
-
+ - For example: "The configuration steps should be completed." can also be read as: "The configuration should be completed BY ZOMBIES".
+ - Instead, you'd write this: "You should complete the configuration steps" or better still, "Complete the configuration steps".
## Language
-* Use US English.
+
+- Use US English.
## Links
-* Make hyperlink descriptions as descriptive as you can. This is a good description:
+
+- Make hyperlink descriptions as descriptive as you can. This is a good description:
> Learn how to [contribute to Vizro](https://vizro.readthedocs.io/en/stable/pages/development/contributing/).
@@ -125,16 +123,16 @@ Don't write this:
> To learn how to contribute to Vizro, see [here](https://vizro.readthedocs.io/en/stable/pages/development/contributing/).
-
### Internal cross-referencing
-We use internal cross-references as follows:
-* For each documentation page, if it helps the reader, we link to narrative documentation (non-API documentation) about each Vizro topic where it is first introduced.
-* On any single page, we limit the repetition of links: do not re-link to the same page again unless there is good reason to do so (for example, linking to a specific sub-section to illustrate a point).
-* Add links to relevant API documentation where it is useful for the reader, and consider how they will navigate from where they land in the API documentation back to the narrative content. Consider adding a link in the relevant docstring back to your page.
+We use internal cross-references as follows:
+- For each documentation page, if it helps the reader, we link to narrative documentation (non-API documentation) about each Vizro topic where it is first introduced.
+- On any single page, we limit the repetition of links: do not re-link to the same page again unless there is good reason to do so (for example, linking to a specific sub-section to illustrate a point).
+- Add links to relevant API documentation where it is useful for the reader, and consider how they will navigate from where they land in the API documentation back to the narrative content. Consider adding a link in the relevant docstring back to your page.
## Oxford commas
+
Use these in lists to avoid confusion. This is confusing:
> The ice cream comes in a range of flavors including banana and strawberry, mango and raspberry and blueberry.
@@ -158,6 +156,7 @@ Simple is not vague, verbose or full of jargon:
> We leverage your existing organizational resources to synthesize novel competencies.
### Friendly
+
Friendly is approachable and open, and it makes discussions flow:
> Vizro: Let’s make cool visualizations happen. Together.
@@ -178,9 +177,10 @@ Functional is not try-hard, cliched or hyperbolic:
## Things to avoid
-* **Gerunds in headings**. What are these? They are the "-ing" forms of verbs. If you find yourself writing "Getting started" in a heading, then consider "Get started" or "How to get started" instead. In fact, in general, it's better to avoid gerund-forms of verbs where you can.
-* **Plagiarism**. Link to their text and credit them.
-* **Colloquialisms**. Avoid them "like the plague" because they may not translate to other regions/languages.
-* **Technical terminology**. This applies particularly to acronyms that do not pass the "Google test". If it is not possible to find their meaning from a simple Google search, don't use them, or explain them with a link or some text.
-* **Business speak**. You can explain simply without using words like "leverage", "utilize" or "facilitate" and still sound clever.
+- **Gerunds in headings**. What are these? They are the "-ing" forms of verbs. If you find yourself writing "Getting started" in a heading, then consider "Get started" or "How to get started" instead. In fact, in general, it's better to avoid gerund-forms of verbs where you can.
+- **Plagiarism**. Link to their text and credit them.
+- **Colloquialisms**. Avoid them "like the plague" because they may not translate to other regions/languages.
+- **Technical terminology**. This applies particularly to acronyms that do not pass the "Google test". If it is not possible to find their meaning from a simple Google search, don't use them, or explain them with a link or some text.
+- **Business speak**. You can explain simply without using words like "leverage", "utilize" or "facilitate" and still sound clever.
+
diff --git a/vizro-core/docs/pages/explanation/faq.md b/vizro-core/docs/pages/explanation/faq.md
index 98dd6f051..084687701 100644
--- a/vizro-core/docs/pages/explanation/faq.md
+++ b/vizro-core/docs/pages/explanation/faq.md
@@ -9,72 +9,60 @@ Here are some answers to frequently asked questions:
-* [Which browsers does Vizro support?](#which-browsers-does-vizro-support)
-* [What is the Vizro versioning policy?](#what-is-the-vizro-versioning-policy)
-* [Where can I find example dashboards?](#where-can-i-find-example-dashboards)
-* [Why should I use Vizro?](#why-should-i-use-vizro)
-* [How does Vizro differ from Dash or Streamlit?](#how-does-vizro-differ-from-dash-or-streamlit)
-* [How does Vizro compare with Python packages and business intelligence (BI) tools?](#how-does-vizro-compare-with-python-packages-and-business-intelligence-bi-tools)
-* [When would an alternative to Vizro be more suitable?](#when-would-an-alternative-to-vizro-be-more-suitable)
-* [How can I report a bug?](#how-can-i-report-a-bug)
-* [How can I request a feature?](#how-can-i-request-a-feature)
-* [I still have a question. Where can I ask it?](#i-still-have-a-question-where-can-i-ask-it)
+- [Which browsers does Vizro support?](#which-browsers-does-vizro-support)
+- [What is the Vizro versioning policy?](#what-is-the-vizro-versioning-policy)
+- [Where can I find example dashboards?](#where-can-i-find-example-dashboards)
+- [Why should I use Vizro?](#why-should-i-use-vizro)
+- [How does Vizro differ from Dash or Streamlit?](#how-does-vizro-differ-from-dash-or-streamlit)
+- [How does Vizro compare with Python packages and business intelligence (BI) tools?](#how-does-vizro-compare-with-python-packages-and-business-intelligence-bi-tools)
+- [When would an alternative to Vizro be more suitable?](#when-would-an-alternative-to-vizro-be-more-suitable)
+- [How can I report a bug?](#how-can-i-report-a-bug)
+- [How can I request a feature?](#how-can-i-request-a-feature)
+- [I still have a question. Where can I ask it?](#i-still-have-a-question-where-can-i-ask-it)
## Which browsers does Vizro support?
-Vizro supports the [Chrome browser](https://www.google.com/intl/en_us/chrome/).
-Other browsers may work, but are not officially supported.
+
+Vizro supports the [Chrome browser](https://www.google.com/intl/en_us/chrome/). Other browsers may work, but are not officially supported.
## What is the Vizro versioning policy?
-This project adheres to [semantic versioning](https://semver.org/spec/v2.0.0.html).
-We do not consider frontend changes (such as changing the appearance of a component) to be breaking changes.
-!!! note
+This project adheres to [semantic versioning](https://semver.org/spec/v2.0.0.html). We do not consider frontend changes (such as changing the appearance of a component) to be breaking changes.
+!!! note
While being in version `0.x.x`, we may introduce breaking changes in minor versions.
-
## Where can I find example dashboards?
For a gallery of examples showing Vizro in action, take a look at [vizro.mckinsey.com](https://vizro.mckinsey.com). The gallery links to the [Vizro HuggingFace collection](https://huggingface.co/vizro), which includes complete code accessed for each example by selecting "Files" in the top right menu.
We also maintain a separate, curated page of [videos, blog posts, and examples of Vizro usage from our community](your-examples.md).
-
## Why should I use Vizro?
-Vizro is a high-level framework built on top of Dash and Pydantic,
-which makes it easier to build advanced dashboards
-since it automates many of the otherwise complex and time-consuming tasks
-traditionally associated with designing, building and deploying front-end applications,
-from prototypes to production.
+Vizro is a high-level framework built on top of Dash and Pydantic, which makes it easier to build advanced dashboards since it automates many of the otherwise complex and time-consuming tasks traditionally associated with designing, building and deploying front-end applications, from prototypes to production.
### You can build beautiful & powerful dashboards, quickly & easily
Users can configure Vizro dashboards without needing to know advanced software development principles, nor how to build front-end applications.
-??? details "See more details"
+??? details "See more details"
- [:octicons-arrow-right-24: Examples](https://vizro.mckinsey.com) - + [:octicons-arrow-right-24: Tutorials](pages/tutorials/explore-components.md) + [:octicons-arrow-right-24: Examples](https://vizro.mckinsey.com) -- :material-scale-balance:{ .lg .middle } __FAQs__ +- :material-scale-balance:{ .lg .middle } __FAQs__ --- - [:octicons-arrow-right-24: How is Vizro different to Streamlit?](pages/explanation/faq.md/#how-does-vizro-differ-from-dash-or-streamlit)
- [:octicons-arrow-right-24: Where can I ask a question about Vizo?](pages/explanation/faq.md/#i-still-have-a-question-where-can-i-ask-it)
- [:octicons-arrow-right-24: Other FAQs](pages/explanation/faq.md)
+ [:octicons-arrow-right-24: How is Vizro different to Streamlit?](pages/explanation/faq.md/#how-does-vizro-differ-from-dash-or-streamlit) + [:octicons-arrow-right-24: Where can I ask a question?](pages/explanation/faq.md/#i-still-have-a-question-where-can-i-ask-it) + [:octicons-arrow-right-24: Other FAQs](pages/explanation/faq.md) -- :fontawesome-solid-hands-holding-circle:{ .lg .middle } __Get involved__ +- :fontawesome-solid-hands-holding-circle:{ .lg .middle } __Get involved__ --- - [:octicons-arrow-right-24: Contribute code](pages/explanation/contributing.md)
+ [:octicons-arrow-right-24: Contribute code](pages/explanation/contributing.md) + [:octicons-arrow-right-24: Contribute to our docs](pages/explanation/documentation-style-guide.md) -- :fontawesome-solid-chart-column:{ .lg .middle } __Vizro-AI__ +- :fontawesome-solid-chart-column:{ .lg .middle } __Vizro-AI__ --- [:octicons-arrow-right-24: Vizro-AI: Use natural language queries to build Plotly charts](https://vizro.readthedocs.io/projects/vizro-ai/) -
- Configuration-driven assembly system of Vizro automatically builds user-friendly, higher-level dashboard concepts (such as a filter) from low-level individual components (for example, a dropdown component plus a filtering function).
- Removes the need for users to learn how to write the “glue code” which combines lower-level components.
- Removes the time taken to write, test and optimize the “glue code” which combines lower-level components.
- Reduces what can be 1000s of lines of code down to dozens of lines of configuration.
Vizro primarily offers configuration to simplify that assembly of components offered by existing packages (currently leveraging Plotly/Dash), and so occupies a slightly different niche from libraries offering primarily the lower-level components themselves. It also removes the requirement from users to implement certain code standards for the assembled code themselves, and therefore saves time on often time consuming things such as writing unit tests and ensuring linting coverage. | Many BI tools incorporate the assembly of higher-level concepts automatically from GUI (drop-and-drag) interfaces, and occupy a slightly different niche to the configuration driven assembly offered by Vizro. | - | **Inbuilt visual design decisions**
- UX decisions such as placement of filters and orientation of charts in relation to other components on the screen.
- Visual design decisions such as chart formatting and spacing between components.
- Colors including text, backgrounds and chart contents.
- Ensures visual consistency within applications, and across applications built by the same user.
- Speeds up development by removing the need to spend time on visual design decisions.
- Removes the need for advanced expertise in visual design.
- Ensures basic color accessibility for most likely color combinations.
Vizro applies that to a wide range of component combinations and complex user flows, offering a holistic and comprehensive approach to automatically enable beautiful visual design best practices, whilst allowing customization and flexibility. | Many BI tools supply inbuilt color choices and visual design choices for certain components.
Vizro offers inbuilt visual design for components in addition to the ability to customize them in a flexible way where needed (for example through CSS), and automatic arrangement of components on the screen. | - | **Inbuilt application architecture decisions**
- The architectural decisions required to connect components in advanced ways - such as combining connecting filters to charts with multi-screen navigation to allow drill-throughs between screens.
- Ensures structural consistency within applications, and across applications built by the same user.
- Speeds up development by removing the need to spend time on architectural decisions or development.
- Removes need for advanced expertise in application architecture.
Vizro applies that to a wide range of component combinations and complex user flows, offering a holistic and comprehensive approach to the entire application architecture, whilst allowing customization and flexibility where relevant. | Many BI tools apply proprietary application architecture by default.
Vizro enables the user to view and understand the application architecture by directly viewing the code. | - | **Declarative configuration, in multiple formats**
- Configuration is declarative and can be written in Python or a configuration language such as YAML, JSON and TOML.
- The range of formats enables flexibility in implementations (and can be extended in future).
- Formats such as YAML support programmatic construction of dashboards (for example being dynamically generated from a Kedro pipeline).
- The focus on editing configuration directly, rather than via GUI or drop-and-drag interfaces, allows for ease of collaboration.
Vizro simplifies this approach, and facilitates the extension of the assembly system to enable integration with other tools such as Kedro to programmatically and dynamically generate the relevant dashboard configurations in a streamlined way. | Many BI tools solely use a GUI and/or drag-and-drop interface for defining dashboards, and leverage proprietary configuration formats.
Vizro enables the user to view and understand the configuration by viewing it directly, in addition to being able to edit it directly. | - | **Mostly tech agnostic “grammar of dashboards”**
- The configuration follows a “grammar of dashboards” which is mostly generic and tech agnostic (rather than being specific to any Python package or coding language).
- Enables a more intuitive understanding of how to write the configuration.
- Enables the configuration to apply to other Python packages or other coding languages in future. (NB: this would require an adjustment to the underlying assembly core code).
Vizro offers a “grammar of dashboards” with declaration which is largely tech agnostic and can be extended to non-Python languages. | Many BI tools utilize an implicit internal “grammar of dashboards” which is specific to the proprietary language(s) on with which they are built.
Vizro offers an explicit configuration grammar and allows users to leverage a mostly tech agnostic approach (which can be extended in future). | - | **Inbuilt validation**
- The ability to leverage Pydantic models automatically give meaningful feedback to users about configuration choices.
- Increases ease of use by guiding users, providing early validation and clear feedback throughout the configuration process.
- This validation feedback can also be utilized by processes which construct the configuration programmatically, such as via a Kedro pipeline.
Vizro offers the advantages of Pydantic based models for many elements of the configuration process, which leverages the validation and guidance inherent in that process to facilitate implementation by users. | Many BI tools have inbuilt guideline systems to ensure components are combined in a valid way, and give feedback to the manual user to help guide through that process.
Vizro utilizes a flexible system which can be extended to give feedback to programmatic generation of configuration. | - | **Modularity**
- The standardization applied by Vizro (in terms of visual design, application architecture and coding standards) makes it possible to reuse configuration, charts, components and extensions such as custom actions, between implementations.
- Speeds up development by allowing reuse of existing implementations.
- Facilitates collaboration between users by allowing knowledge to be encoded in modular ways.
Vizro supports modularity of groups of components (such as their implementation together as a dashboard screen), which can be easily transferred between implementations as configuration. | Many BI tools supply extensions and plugins which support modularity of visualizations.
Vizro supports modularity of groups of components (such as their implementation together as a dashboard screen), which can be easily transferred between implementations as configuration. | - | **Flexibility**
- The ability to utilize the low-code approach of configuration with the high-code approach of custom functions offers flexibility in implementation for both less technical and more technical users.
- The low-code configuration driven approach enables all users to create fairly flexible dashboards easily.
- The high-code approach of using custom functions in a structured way gives more technical users with flexibility to extend functionality almost infinitely.
Vizro supports a holistic combination of low-code and high-code approaches which support less technical and more technical users individually while allowing them much flexibility in implementation according to their technical level. | Many BI tools offer a no-code (or at least low-code) approach to creating charts and dashboards, along with varying forms of plugins to increase flexibility.
Vizro unlocks Python custom functions to be able to power this user driven flexibility in a technically advanced way, with a high degree of control and visibility over the code, whilst also supporting less technical users through low-code configuration. | - | **Scaling**
- The consistency in visual design, application architecture and code standards, combined with the ease of collaboration between Python developers, allows scaling within and between projects by facilitating reuse, extension and programmatic updates of configurations.
- Sections of configuration can be reused and tailored easily, allowing implementations to scale across or between projects.
- New joiners to a team can get up to speed quickly, allowing teams to scale in size.
- Other teams can inherit configurations easily, allowing implementations to scale between teams.
- Updates can be propagated to configurations from a central location, allowing adjustments and updates to scale easily across large implementations.
- Inbuilt visual design decisions offer visual consistency.
- Leveraging collaborative coding mechanisms such as Git enables almost any number of developers to collaborate effectively.
Vizro makes it easy to scale by replicating the relatively small amount of configuration in 1 file between usages, rather than replicating a large amount of code across many files between usages.
Updating configuration programmatically from a central location is often easier than updating code. When sharing between users, it can be easier to inherit and understand configuration than the underlying code. The visual consistency makes it easier to scale within or between projects while maintaining visual coherence. | Many BI tools allow scaling through GUI drag-and-drop interfaces (having some functionality for duplication or propagating changes) for single users.
Vizro makes it easy to leverage tools such as Git to enable almost any number of users to collaborate effectively, therefore allowing the number of developers on a single project to scale easily.
Since updates can be propagated programmatically easily from a central location, it allows scaling across almost any number of related implementations which can be kept up to date and aligned without the need to manually adjust each implementation when updates are required. | - | **Python first**
- Leveraging Pydantic and Plotly/Dash give a Python first approach (whilst making use of a mostly tech agnostic configuration system).
- (Since Plotly/Dash leverage React components, and allow them to be used as components, then JavaScript can also be used in a form that is effectively wrapped in Python).
- This empowers a wider group of practitioners that are already close to data analytics, since they are more likely to have existing skills in Python than JavaScript.
- This offers the advantage of leveraging existing Python work spaces such as notebooks and IDEs.
- Facilitates multi-developer collaboration via tools such as Git.
Vizro is no different in this respect. By leveraging Plotly/Dash, Vizro is also able to benefit from the power and flexibility offered by JavaScript via React, whilst still presenting a format that is Python first to the user (by making use of the ability offered by Dash to effectively wrap those components into Python). | Many BI tools do not offer direct or full integration with Python.
Vizro supports a Python first approach which leverages the power and flexibility of Python, and the open source community supporting that wide ranging functionality. | - | **Open source**
- The use of an open source license, and the reliance on open source packages.
- The provision of ongoing development and maintenance.
- There is no license fee required to utilize Vizro.
- Ongoing development and maintenance increases the long term usability of the Vizro package, and viability of implementations.
Vizro is no different in this respect. | Many BI tools follow a license fee model and/or charge for ongoing development and maintenance.
Vizro requires no license fee, and offers ongoing development and support, which helps to remove some barriers to usage. | + | Functionality | Benefits | In context of Python packages | In context of BI tools | + | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | **Assembly system**
- Configuration-driven assembly system of Vizro automatically builds user-friendly, higher-level dashboard concepts (such as a filter) from low-level individual components (for example, a dropdown component plus a filtering function).
- Removes the need for users to learn how to write the “glue code” which combines lower-level components.
- Removes the time taken to write, test and optimize the “glue code” which combines lower-level components.
- Reduces what can be 1000s of lines of code down to dozens of lines of configuration.
Vizro primarily offers configuration to simplify that assembly of components offered by existing packages (currently leveraging Plotly/Dash), and so occupies a slightly different niche from libraries offering primarily the lower-level components themselves. It also removes the requirement from users to implement certain code standards for the assembled code themselves, and therefore saves time on often time consuming things such as writing unit tests and ensuring linting coverage. | Many BI tools incorporate the assembly of higher-level concepts automatically from GUI (drop-and-drag) interfaces, and occupy a slightly different niche to the configuration driven assembly offered by Vizro. | + | **Inbuilt visual design decisions**
- UX decisions such as placement of filters and orientation of charts in relation to other components on the screen.
- Visual design decisions such as chart formatting and spacing between components.
- Colors including text, backgrounds and chart contents.
- Ensures visual consistency within applications, and across applications built by the same user.
- Speeds up development by removing the need to spend time on visual design decisions.
- Removes the need for advanced expertise in visual design.
- Ensures basic color accessibility for most likely color combinations.
Vizro applies that to a wide range of component combinations and complex user flows, offering a holistic and comprehensive approach to automatically enable beautiful visual design best practices, whilst allowing customization and flexibility. | Many BI tools supply inbuilt color choices and visual design choices for certain components.
Vizro offers inbuilt visual design for components in addition to the ability to customize them in a flexible way where needed (for example through CSS), and automatic arrangement of components on the screen. | + | **Inbuilt application architecture decisions**
- The architectural decisions required to connect components in advanced ways - such as combining connecting filters to charts with multi-screen navigation to allow drill-throughs between screens.
- Ensures structural consistency within applications, and across applications built by the same user.
- Speeds up development by removing the need to spend time on architectural decisions or development.
- Removes need for advanced expertise in application architecture.
Vizro applies that to a wide range of component combinations and complex user flows, offering a holistic and comprehensive approach to the entire application architecture, whilst allowing customization and flexibility where relevant. | Many BI tools apply proprietary application architecture by default.
Vizro enables the user to view and understand the application architecture by directly viewing the code. | + | **Declarative configuration, in multiple formats**
- Configuration is declarative and can be written in Python or a configuration language such as YAML, JSON and TOML.
- The range of formats enables flexibility in implementations (and can be extended in future).
- Formats such as YAML support programmatic construction of dashboards (for example being dynamically generated from a Kedro pipeline).
- The focus on editing configuration directly, rather than via GUI or drop-and-drag interfaces, allows for ease of collaboration.
Vizro simplifies this approach, and facilitates the extension of the assembly system to enable integration with other tools such as Kedro to programmatically and dynamically generate the relevant dashboard configurations in a streamlined way. | Many BI tools solely use a GUI and/or drag-and-drop interface for defining dashboards, and leverage proprietary configuration formats.
Vizro enables the user to view and understand the configuration by viewing it directly, in addition to being able to edit it directly. | + | **Mostly tech agnostic “grammar of dashboards”**
- The configuration follows a “grammar of dashboards” which is mostly generic and tech agnostic (rather than being specific to any Python package or coding language).
- Enables a more intuitive understanding of how to write the configuration.
- Enables the configuration to apply to other Python packages or other coding languages in future. (NB: this would require an adjustment to the underlying assembly core code).
Vizro offers a “grammar of dashboards” with declaration which is largely tech agnostic and can be extended to non-Python languages. | Many BI tools utilize an implicit internal “grammar of dashboards” which is specific to the proprietary language(s) on with which they are built.
Vizro offers an explicit configuration grammar and allows users to leverage a mostly tech agnostic approach (which can be extended in future). | + | **Inbuilt validation**
- The ability to leverage Pydantic models automatically give meaningful feedback to users about configuration choices.
- Increases ease of use by guiding users, providing early validation and clear feedback throughout the configuration process.
- This validation feedback can also be utilized by processes which construct the configuration programmatically, such as via a Kedro pipeline.
Vizro offers the advantages of Pydantic based models for many elements of the configuration process, which leverages the validation and guidance inherent in that process to facilitate implementation by users. | Many BI tools have inbuilt guideline systems to ensure components are combined in a valid way, and give feedback to the manual user to help guide through that process.
Vizro utilizes a flexible system which can be extended to give feedback to programmatic generation of configuration. | + | **Modularity**
- The standardization applied by Vizro (in terms of visual design, application architecture and coding standards) makes it possible to reuse configuration, charts, components and extensions such as custom actions, between implementations.
- Speeds up development by allowing reuse of existing implementations.
- Facilitates collaboration between users by allowing knowledge to be encoded in modular ways.
Vizro supports modularity of groups of components (such as their implementation together as a dashboard screen), which can be easily transferred between implementations as configuration. | Many BI tools supply extensions and plugins which support modularity of visualizations.
Vizro supports modularity of groups of components (such as their implementation together as a dashboard screen), which can be easily transferred between implementations as configuration. | + | **Flexibility**
- The ability to utilize the low-code approach of configuration with the high-code approach of custom functions offers flexibility in implementation for both less technical and more technical users.
- The low-code configuration driven approach enables all users to create fairly flexible dashboards easily.
- The high-code approach of using custom functions in a structured way gives more technical users with flexibility to extend functionality almost infinitely.
Vizro supports a holistic combination of low-code and high-code approaches which support less technical and more technical users individually while allowing them much flexibility in implementation according to their technical level. | Many BI tools offer a no-code (or at least low-code) approach to creating charts and dashboards, along with varying forms of plugins to increase flexibility.
Vizro unlocks Python custom functions to be able to power this user driven flexibility in a technically advanced way, with a high degree of control and visibility over the code, whilst also supporting less technical users through low-code configuration. | + | **Scaling**
- The consistency in visual design, application architecture and code standards, combined with the ease of collaboration between Python developers, allows scaling within and between projects by facilitating reuse, extension and programmatic updates of configurations.
- Sections of configuration can be reused and tailored easily, allowing implementations to scale across or between projects.
- New joiners to a team can get up to speed quickly, allowing teams to scale in size.
- Other teams can inherit configurations easily, allowing implementations to scale between teams.
- Updates can be propagated to configurations from a central location, allowing adjustments and updates to scale easily across large implementations.
- Inbuilt visual design decisions offer visual consistency.
- Leveraging collaborative coding mechanisms such as Git enables almost any number of developers to collaborate effectively.
Vizro makes it easy to scale by replicating the relatively small amount of configuration in 1 file between usages, rather than replicating a large amount of code across many files between usages.
Updating configuration programmatically from a central location is often easier than updating code. When sharing between users, it can be easier to inherit and understand configuration than the underlying code. The visual consistency makes it easier to scale within or between projects while maintaining visual coherence. | Many BI tools allow scaling through GUI drag-and-drop interfaces (having some functionality for duplication or propagating changes) for single users.
Vizro makes it easy to leverage tools such as Git to enable almost any number of users to collaborate effectively, therefore allowing the number of developers on a single project to scale easily.
Since updates can be propagated programmatically easily from a central location, it allows scaling across almost any number of related implementations which can be kept up to date and aligned without the need to manually adjust each implementation when updates are required. | + | **Python first**
- Leveraging Pydantic and Plotly/Dash give a Python first approach (whilst making use of a mostly tech agnostic configuration system).
- (Since Plotly/Dash leverage React components, and allow them to be used as components, then JavaScript can also be used in a form that is effectively wrapped in Python).
- This empowers a wider group of practitioners that are already close to data analytics, since they are more likely to have existing skills in Python than JavaScript.
- This offers the advantage of leveraging existing Python work spaces such as notebooks and IDEs.
- Facilitates multi-developer collaboration via tools such as Git.
Vizro is no different in this respect. By leveraging Plotly/Dash, Vizro is also able to benefit from the power and flexibility offered by JavaScript via React, whilst still presenting a format that is Python first to the user (by making use of the ability offered by Dash to effectively wrap those components into Python). | Many BI tools do not offer direct or full integration with Python.
Vizro supports a Python first approach which leverages the power and flexibility of Python, and the open source community supporting that wide ranging functionality. | + | **Open source**
- The use of an open source license, and the reliance on open source packages.
- The provision of ongoing development and maintenance.
- There is no license fee required to utilize Vizro.
- Ongoing development and maintenance increases the long term usability of the Vizro package, and viability of implementations.
Vizro is no different in this respect. | Many BI tools follow a license fee model and/or charge for ongoing development and maintenance.
Vizro requires no license fee, and offers ongoing development and support, which helps to remove some barriers to usage. | ## When would an alternative to Vizro be more suitable? @@ -162,18 +130,14 @@ There are a number of cases where alternatives to Vizro may be more suitable, in - where Python developers are already very comfortable leveraging other Python packages - - ## How can I report a bug? Head over to our [GitHub issues](https://github.com/mckinsey/vizro/issues) and [create a new bug report](https://github.com/mckinsey/vizro/issues/new/choose). We will try to reproduce the bug you've reported and follow up with the next steps. - ## How can I request a feature? To raise a feature request, head to our [GitHub issues](https://github.com/mckinsey/vizro/issues) and [create a new feature request](https://github.com/mckinsey/vizro/issues/new/choose). The team will then try to understand the request in more detail, explore the feasibility and prioritize it in relation to the current roadmap. We will get back to you as soon as possible with an estimate of whether and when this feature could be released. - ## I still have a question. Where can I ask it? We are happy to receive general questions around Vizro. Take a look at our [GitHub issues](https://github.com/mckinsey/vizro/issues) and [create a new issue](https://github.com/mckinsey/vizro/issues/new/choose) by clicking "General question". diff --git a/vizro-core/docs/pages/explanation/your-examples.md b/vizro-core/docs/pages/explanation/your-examples.md index 6f1da044a..91a0baa2b 100644 --- a/vizro-core/docs/pages/explanation/your-examples.md +++ b/vizro-core/docs/pages/explanation/your-examples.md @@ -4,37 +4,43 @@ This page lists videos, blog posts, and examples of Vizro usage in repositories If you have something you'd like us to include on the list, or spot something that we should include, let us know: -* you can [raise an issue](https://github.com/mckinsey/vizro/issues) on the Vizro repository, -* better still, you can [make a PR to contribute](../explanation/contributing.md) to this page. - +- you can [raise an issue](https://github.com/mckinsey/vizro/issues) on the Vizro repository, +- better still, you can [make a PR to contribute](../explanation/contributing.md) to this page. !!! note - The Vizro team and QuantumBlack, AI by McKinsey, do not take responsibility for third party content. In curating the list below, we may inspect or test an example at time of inclusion, but cannot guarantee the content thereafter. ## Videos -* From [Charming Data on YouTube](https://www.youtube.com/@CharmingData): - * [Build Python Data Apps with Vizro Dash](https://www.youtube.com/watch?v=wmQ6_GZ0zSk). - * [Introduction to Vizro Actions - Plotly Dash](https://www.youtube.com/watch?v=bom-9275Cic&t=8s). - * [Use Dash AG Grid within a Vizro app](https://www.youtube.com/watch?v=YvtVcXwQw0E). - * [Visual Vocabulary Dashboard showcasing charting options in Vizro and Plotly](https://www.youtube.com/watch?v=OZNAokBKT-M). +- From [Charming Data on YouTube](https://www.youtube.com/@CharmingData): + - [Build Python Data Apps with Vizro Dash](https://www.youtube.com/watch?v=wmQ6_GZ0zSk). + - [Introduction to Vizro Actions - Plotly Dash](https://www.youtube.com/watch?v=bom-9275Cic&t=8s). + - [Use Dash AG Grid within a Vizro app](https://www.youtube.com/watch?v=YvtVcXwQw0E). + - [Visual Vocabulary Dashboard showcasing charting options in Vizro and Plotly](https://www.youtube.com/watch?v=OZNAokBKT-M). ## Blog posts -* [Introducing Vizro](https://quantumblack.medium.com/introducing-vizro-a-toolkit-for-creating-modular-data-visualization-applications-3a42f2bec4db). -* [Creating Custom Dashboards with Vizro: A Comprehensive Guide](https://medium.com/@saffand03/creating-custom-dashboards-with-vizro-a-comprehensive-guide-73c69c6f851e). + +- [Introducing Vizro](https://quantumblack.medium.com/introducing-vizro-a-toolkit-for-creating-modular-data-visualization-applications-3a42f2bec4db). +- [Creating Custom Dashboards with Vizro: A Comprehensive Guide](https://medium.com/@saffand03/creating-custom-dashboards-with-vizro-a-comprehensive-guide-73c69c6f851e). + -* [I built a reusable dashboard read-the-docs traffic analytics using vizro](https://medium.com/towards-data-science/i-built-a-reusable-dashboard-for-read-the-docs-traffic-analytics-using-vizro-47dc15dc04f8). + +- [I built a reusable dashboard read-the-docs traffic analytics using vizro](https://medium.com/towards-data-science/i-built-a-reusable-dashboard-for-read-the-docs-traffic-analytics-using-vizro-47dc15dc04f8). + -* [Visualizing data science insights](https://medium.com/quantumblack/visualizing-data-science-insights-dfc8ad0646b6). + +- [Visualizing data science insights](https://medium.com/quantumblack/visualizing-data-science-insights-dfc8ad0646b6). + -* [A low-code, attractive, sharable data dashboard: Illustrating my LinkedIn connections in 100 lines of Python](https://medium.com/design-bootcamp/a-low-code-attractive-sharable-data-dashboard-a60badba2a03). + +- [A low-code, attractive, sharable data dashboard: Illustrating my LinkedIn connections in 100 lines of Python](https://medium.com/design-bootcamp/a-low-code-attractive-sharable-data-dashboard-a60badba2a03). ## Examples on GitHub or PyCafe -* [Personal Vizro app demos by Vizro team member `huong-li-nguyen`](https://github.com/huong-li-nguyen/vizro-app-demos). -* [Proof of concept example by `viiviandias`](https://github.com/viiviandias/poc-vizro/blob/main/brasil_stocks.ipynb). -* [Amazon sales analysis by `Bottleneck44`](https://github.com/Bottleneck44/Amazon-Sales-Analysis/blob/main/Amazon-analysis.ipynb). -* [Insight-AI: Chart and business insight generation by `micky091` using vizro-ai](https://github.com/micky0919/insight-ai) -* [Music trend analysis using Vizro](https://py.cafe/app/KhushaliP/vizro-music-trend-analysis) by [`KhushaliP`](https://github.com/KhushaliP) +- [Personal Vizro app demos by Vizro team member `huong-li-nguyen`](https://github.com/huong-li-nguyen/vizro-app-demos). +- [Proof of concept example by `viiviandias`](https://github.com/viiviandias/poc-vizro/blob/main/brasil_stocks.ipynb). +- [Amazon sales analysis by `Bottleneck44`](https://github.com/Bottleneck44/Amazon-Sales-Analysis/blob/main/Amazon-analysis.ipynb). +- [Insight-AI: Chart and business insight generation by `micky091` using vizro-ai](https://github.com/micky0919/insight-ai) +- [Music trend analysis using Vizro](https://py.cafe/app/KhushaliP/vizro-music-trend-analysis) by [`KhushaliP`](https://github.com/KhushaliP) + diff --git a/vizro-core/docs/pages/tutorials/explore-components.md b/vizro-core/docs/pages/tutorials/explore-components.md index 52a0ef3e3..a770dacf1 100644 --- a/vizro-core/docs/pages/tutorials/explore-components.md +++ b/vizro-core/docs/pages/tutorials/explore-components.md @@ -23,12 +23,10 @@ Vizro uses [`Graph`][vizro.models.Graph] objects and [Plotly Express functions]( The code below shows the steps necessary to add a box plot to the page: 1. Add a Vizro [`Graph`][vizro.models.Graph] to the `components` list. -2. Add a [`plotly.express.box`](https://plotly.com/python-api-reference/generated/plotly.express.box.html#plotly.express.box) figure to the list of components. - +1. Add a [`plotly.express.box`](https://plotly.com/python-api-reference/generated/plotly.express.box.html#plotly.express.box) figure to the list of components. !!! example "First component" === "app.py" - ```{.python pycafe-link} from vizro import Vizro import vizro.models as vm @@ -55,23 +53,19 @@ The code below shows the steps necessary to add a box plot to the page: ``` === "Result" - - [![FirstPage1]][FirstPage1] - - [FirstPage1]: ../../assets/tutorials/dashboard/dashboard21.png - + [![FirstPage1]][firstpage1] ??? note "To run the dashboard in a Notebook or script" - Paste the above code into a Notebook cell, run the Notebook, and evaluate it. --- + If you prefer to use Python scripts to Notebooks, here's how to try out the dashboard: 1. Create a new script called `app.py`. - 2. Copy the code above into the script. - 3. Navigate to the directory where `app.py` file is located using your terminal. - 4. Run the script by executing the command `python app.py`. + 1. Copy the code above into the script. + 1. Navigate to the directory where `app.py` file is located using your terminal. + 1. Run the script by executing the command `python app.py`. Once the script is running, open your web browser and go to `localhost:8050`. You should see the dashboard page with the gapminder data displayed, as shown in the `Result` tab above. @@ -83,11 +77,10 @@ You can combine and arrange various types of `components` on a dashboard page. T The code below adds two components to the page: -* A [`Card`][vizro.models.Card] to insert markdown text into the dashboard. -* A [`Graph`][vizro.models.Graph] to illustrate GDP development per continent since 1952 as a line graph. +- A [`Card`][vizro.models.Card] to insert markdown text into the dashboard. +- A [`Graph`][vizro.models.Graph] to illustrate GDP development per continent since 1952 as a line graph. !!! warning "Before you run this code in a Jupyter Notebook" - If you are following this tutorial in a Jupyter Notebook, you need to restart the kernel each time you evaluate the code. If you do not, you will see error messages such as "Components must uniquely map..." because those components already exist from the previous evaluation. !!! example "Add components" @@ -103,6 +96,7 @@ The code below adds two components to the page: ) ``` + === "Code second component" ```py @@ -113,8 +107,8 @@ The code below adds two components to the page: "gdpPercap":"GDP Per Cap"}, title=''), ) ``` - === "app.py" + === "app.py" ```{.python pycafe-link} from vizro import Vizro import vizro.models as vm @@ -152,15 +146,13 @@ The code below adds two components to the page: dashboard = vm.Dashboard(pages=[first_page]) Vizro().build(dashboard).run() ``` - === "Result" - [![FirstPage2]][FirstPage2] - [FirstPage2]: ../../assets/tutorials/dashboard/dashboard22.png + === "Result" + [![FirstPage2]][firstpage2] As you explore the dashboard, you may notice that the current layout could be further enhanced. The charts appear cramped, while the text component has ample unused space. The next section explains how to configure the layout and arrange the components. !!! note "An introduction to Vizro-AI" - In the example above, the code to create the line graph was generated using [Vizro-AI](https://vizro.readthedocs.io/en/latest/pages/tutorials/first-dashboard/). Vizro-AI enables you to use English, or other languages, to create interactive charts with [Plotly](https://plotly.com/python/) by simplifying the process through use of a large language model. In essence, Vizro-AI generates code from natural language instructions so that you can add it into a Vizro dashboard, such as in the example above. Find out more in the [Vizro-AI documentation](https://vizro.readthedocs.io/projects/vizro-ai/)! @@ -169,32 +161,23 @@ As you explore the dashboard, you may notice that the current layout could be fu By default, Vizro places each element in the order it was added to `components` list, and spaces them equally. -You can use the [`Layout`][vizro.models.Layout] object to specify the placement and size of components on the page. To learn more about how to -configure layouts, check out [How to use layouts](../user-guides/layouts.md). +You can use the [`Layout`][vizro.models.Layout] object to specify the placement and size of components on the page. To learn more about how to configure layouts, check out [How to use layouts](../user-guides/layouts.md). -The following layout configuration positions the text at the top and the two charts side -by side, giving them more space relative to the text component: +The following layout configuration positions the text at the top and the two charts side by side, giving them more space relative to the text component: ```python -grid=[ [0, 0], - [1, 2], - [1, 2], - [1, 2] ] +grid = [[0, 0], [1, 2], [1, 2], [1, 2]] ``` -Vizro interprets these values as follows. First, the configuration divides the available space into two columns and -four rows. Each element in the list (such as `[0,0]`) represents one row of the grid layout: +Vizro interprets these values as follows. First, the configuration divides the available space into two columns and four rows. Each element in the list (such as `[0,0]`) represents one row of the grid layout:  -Each element in the `components` list is referenced with a unique number, and placed on the grid as visualized with the white frames. The `Card`, is referenced by 0 as it is the first element in the `components` list. It is placed in the first row and spans across both -columns (`[0, 0]`). The two `Graph` objects, referenced by 1 and 2, are positioned next to each other and occupy a column each. +Each element in the `components` list is referenced with a unique number, and placed on the grid as visualized with the white frames. The `Card`, is referenced by 0 as it is the first element in the `components` list. It is placed in the first row and spans across both columns (`[0, 0]`). The two `Graph` objects, referenced by 1 and 2, are positioned next to each other and occupy a column each.  -The `Graph` objects occupy three rows, denoted by `[1, 2], [1, 2], [1, 2]`, while the -`Card` only occupies one row `[0, 0]`. As a result, the `Graph` objects occupy three-quarters of the vertical space, while the -`Card` occupies one-quarter of it. +The `Graph` objects occupy three rows, denoted by `[1, 2], [1, 2], [1, 2]`, while the `Card` only occupies one row `[0, 0]`. As a result, the `Graph` objects occupy three-quarters of the vertical space, while the `Card` occupies one-quarter of it.  @@ -205,8 +188,8 @@ Run the code below to apply the layout to the dashboard page: ```py layout=vm.Layout(grid=[[0, 0], [1, 2], [1, 2], [1, 2]]) ``` - === "app.py" + === "app.py" ```{.python pycafe-link} from vizro import Vizro import vizro.models as vm @@ -244,32 +227,24 @@ Run the code below to apply the layout to the dashboard page: dashboard = vm.Dashboard(pages=[first_page]) Vizro().build(dashboard).run() ``` - === "Result" - [![FirstPage3]][FirstPage3] - - [FirstPage3]: ../../assets/tutorials/dashboard/dashboard23.png + === "Result" + [![FirstPage3]][firstpage3] ### 2.4. Add a control for dashboard interactivity -Controls add interactivity to the dashboard page and make it more dynamic, enabling users -to have greater control and customization over the displayed data and components. +Controls add interactivity to the dashboard page and make it more dynamic, enabling users to have greater control and customization over the displayed data and components. There are two types of control: -* [`Filters`][vizro.models.Filter] enable users to filter a column of the underlying data. -* [`Parameters`][vizro.models.Parameter] enable users to change arguments or properties of the components, such as adjusting colors. - +- [`Filters`][vizro.models.Filter] enable users to filter a column of the underlying data. +- [`Parameters`][vizro.models.Parameter] enable users to change arguments or properties of the components, such as adjusting colors. The guides on [`How to use Filters`](../user-guides/filters.md) and [`How to use Parameters`](../user-guides/parameters.md) offer instructions on their application. For further customization, refer to the guide on [`How to use selectors`](../user-guides/selectors.md). To link a control to a component, use an `id` assigned to the component, which is unique across all dashboard pages and serves as a reference to target it. -To illustrate, let's add a [`Filter`][vizro.models.Filter] on specific -continents of the underlying gapminder data. The [`Filter`][vizro.models.Filter] requires the `column` argument, that denotes -the target column to be filtered. Each `control` also has a `targets` parameter, to specify the -data and components targeted by the `control`. For this dashboard, both charts -are listed in the `targets` parameter, meaning that the filter is be applied to both charts. However, you can apply the [`Filter`][vizro.models.Filter] to only one specific chart if required. +To illustrate, let's add a [`Filter`][vizro.models.Filter] on specific continents of the underlying gapminder data. The [`Filter`][vizro.models.Filter] requires the `column` argument, that denotes the target column to be filtered. Each `control` also has a `targets` parameter, to specify the data and components targeted by the `control`. For this dashboard, both charts are listed in the `targets` parameter, meaning that the filter is be applied to both charts. However, you can apply the [`Filter`][vizro.models.Filter] to only one specific chart if required. !!! example "Configure filter" === "Code" @@ -278,8 +253,8 @@ are listed in the `targets` parameter, meaning that the filter is be applied to vm.Filter(column="continent", targets=["box_cont", "line_gdp"]), ] ``` - === "app.py" + === "app.py" ```{.python pycafe-link} from vizro import Vizro import vizro.models as vm @@ -324,16 +299,14 @@ are listed in the `targets` parameter, meaning that the filter is be applied to ``` === "Result" - [![FirstPage4]][FirstPage4] - - [FirstPage4]: ../../assets/tutorials/dashboard/dashboard24.png + [![FirstPage4]][firstpage4] Fantastic job! You have completed first dashboard page and gained valuable skills to: 1. [Create an initial figure on a dashboard page](#2-create-a-first-dashboard-page) -2. [Add extra components](#22-add-further-components) -3. [Arrange them in a layout configuration](#23-configure-the-layout) -4. [Set up an interactive dashboard control](#24-add-a-control-for-dashboard-interactivity). +1. [Add extra components](#22-add-further-components) +1. [Arrange them in a layout configuration](#23-configure-the-layout) +1. [Set up an interactive dashboard control](#24-add-a-control-for-dashboard-interactivity). ## 3. Create a second dashboard page @@ -343,16 +316,10 @@ Every [`Page`][vizro.models.Page] that you want to display needs to be added to In creating a [`Parameter`][vizro.models.Parameter] object, you define the `target` it applies to. In the code below: -* The first parameter enables the user to change the color mapping for the `virginica` category of the iris data, targeting both charts. -* The second parameter adjusts the opacity of the first chart alone, through `scatter_iris.opacity`. - +- The first parameter enables the user to change the color mapping for the `virginica` category of the iris data, targeting both charts. +- The second parameter adjusts the opacity of the first chart alone, through `scatter_iris.opacity`. -In general, `targets` for [`Parameters`][vizro.models.Parameter] are set following the structure of -`component_id.argument`. In certain cases, you may see a nested structure for the `targets`. An example of this is -`scatter_iris.color_discrete_map.virginica`. A nested structure targets a specific attribute within a -component. In this particular example, it specifies that only the color of the virginica flower type should be changed. -More information on how to set `targets` for [`Parameters`][vizro.models.Parameter] can be found in the [how-to guide -for parameters](../user-guides/parameters.md). +In general, `targets` for [`Parameters`][vizro.models.Parameter] are set following the structure of `component_id.argument`. In certain cases, you may see a nested structure for the `targets`. An example of this is `scatter_iris.color_discrete_map.virginica`. A nested structure targets a specific attribute within a component. In this particular example, it specifies that only the color of the virginica flower type should be changed. More information on how to set `targets` for [`Parameters`][vizro.models.Parameter] can be found in the [how-to guide for parameters](../user-guides/parameters.md). !!! example "Second page" === "Code" @@ -392,8 +359,8 @@ for parameters](../user-guides/parameters.md). ], ) ``` - === "app.py" + === "app.py" ```{.python pycafe-link} from vizro import Vizro import vizro.models as vm @@ -470,25 +437,19 @@ for parameters](../user-guides/parameters.md). dashboard = vm.Dashboard(pages=[first_page,second_page]) Vizro().build(dashboard).run() ``` - === "Result" - [![SecondPage]][SecondPage] - [SecondPage]: ../../assets/tutorials/dashboard/dashboard3.png + === "Result" + [![SecondPage]][secondpage] ### 3.1. Customize with selectors -The code in the example above uses two different types of [`selector`](../user-guides/selectors.md) objects, namely -[`Dropdown`][vizro.models.Dropdown] and [`Slider`][vizro.models.Slider] upon the -[`Parameters`][vizro.models.Parameter]. The `selectors` enable configuration of the controls to customize their behavior and appearance. +The code in the example above uses two different types of [`selector`](../user-guides/selectors.md) objects, namely [`Dropdown`][vizro.models.Dropdown] and [`Slider`][vizro.models.Slider] upon the [`Parameters`][vizro.models.Parameter]. The `selectors` enable configuration of the controls to customize their behavior and appearance. -The first parameter is a [`Dropdown`][vizro.models.Dropdown]. It is configured with two available -options, disables multi-selection, and has a default `value` set to blue. Users can choose a single option -from the dropdown. +The first parameter is a [`Dropdown`][vizro.models.Dropdown]. It is configured with two available options, disables multi-selection, and has a default `value` set to blue. Users can choose a single option from the dropdown. The second parameter is a [`Slider`][vizro.models.Slider] with a default value of 0.8. Users can adjust a value within the specified range of `min=0` and `max=1`. -You can apply selectors to configure [`Filters`][vizro.models.Filter] and -[`Parameters`][vizro.models.Parameter] to fine-tune the behavior and appearance of the controls. The selectors currently available are as follows: +You can apply selectors to configure [`Filters`][vizro.models.Filter] and [`Parameters`][vizro.models.Parameter] to fine-tune the behavior and appearance of the controls. The selectors currently available are as follows: - [`Parameter`][vizro.models.Parameter]: - [`Checklist`][vizro.models.Checklist] @@ -499,24 +460,17 @@ You can apply selectors to configure [`Filters`][vizro.models.Filter] and ## 4. The final touches -This section puts everything together by adding a -homepage to the example for navigation between the two separate pages. +This section puts everything together by adding a homepage to the example for navigation between the two separate pages. -For easy navigation within your dashboard, we'll create a page that serves as the entry point for the user. -On this homepage are two [`Cards`][vizro.models.Card] which serve as tiles that can be customized with a title, some text, and an -image. These cards link to the subpages within your dashboard using their `href` attributes as `href="/first-page"` and `href="/second-page"`. This -establishes the navigation links from the homepage to each of the subpages. +For easy navigation within your dashboard, we'll create a page that serves as the entry point for the user. On this homepage are two [`Cards`][vizro.models.Card] which serve as tiles that can be customized with a title, some text, and an image. These cards link to the subpages within your dashboard using their `href` attributes as `href="/first-page"` and `href="/second-page"`. This establishes the navigation links from the homepage to each of the subpages. -Each page is added to the dashboard using the following line of code: -`vm.Dashboard(pages=[home_page, first_page, second_page])`. This ensures that all the pages are accessible. +Each page is added to the dashboard using the following line of code: `vm.Dashboard(pages=[home_page, first_page, second_page])`. This ensures that all the pages are accessible. -The code below illustrates a functional dashboard where you can navigate from the homepage to each -of the subpages. Additionally, you can use the navigation panel on the left side to switch between the three pages. +The code below illustrates a functional dashboard where you can navigate from the homepage to each of the subpages. Additionally, you can use the navigation panel on the left side to switch between the three pages. !!! example "Final dashboard" - === "Code" - ```py + ```python home_page = vm.Page( title="Homepage", components=[ @@ -542,12 +496,13 @@ of the subpages. Additionally, you can use the navigation panel on the left side ), ], ) - ``` - ```py + + ... + dashboard = vm.Dashboard(pages=[home_page, first_page, second_page]) ``` - === "app.py" + === "app.py" ```{.python pycafe-link} from vizro import Vizro @@ -651,31 +606,23 @@ of the subpages. Additionally, you can use the navigation panel on the left side dashboard = vm.Dashboard(pages=[home_page, first_page, second_page]) Vizro().build(dashboard).run() ``` - === "Homepage" - [![FinalPage]][FinalPage] - [FinalPage]: ../../assets/tutorials/dashboard/dashboard4.png + === "Homepage" + [![FinalPage]][finalpage] === "Subpage1" - [![FinalPage1]][FinalPage1] - - [FinalPage1]: ../../assets/tutorials/dashboard/dashboard2.png + [![FinalPage1]][finalpage1] === "Subpage2" - [![FinalPage2]][FinalPage2] + [![FinalPage2]][finalpage2] - [FinalPage2]: ../../assets/tutorials/dashboard/dashboard3.png - -Congratulations on completing this tutorial! You have acquired the knowledge to configure layouts, add components, and -implement interactivity in Vizro dashboards, working across two navigable pages. +Congratulations on completing this tutorial! You have acquired the knowledge to configure layouts, add components, and implement interactivity in Vizro dashboards, working across two navigable pages. ## Find out more After completing the tutorial you now have a solid understanding of the main elements of Vizro and how to bring them together to create dynamic and interactive data visualizations. -You can find out more about the Vizro by reading the [components overview page](../user-guides/components.md). To gain more in-depth knowledge about the usage and configuration details of individual controls, check out the guides dedicated to [Filters](../user-guides/filters.md), [Parameters](../user-guides/parameters.md) -and [Selectors](../user-guides/selectors.md). If you'd like to understand more about different ways to configure the navigation of your dashboard, head -to [Navigation](../user-guides/navigation.md). +You can find out more about the Vizro by reading the [components overview page](../user-guides/components.md). To gain more in-depth knowledge about the usage and configuration details of individual controls, check out the guides dedicated to [Filters](../user-guides/filters.md), [Parameters](../user-guides/parameters.md), and [Selectors](../user-guides/selectors.md). If you'd like to understand more about different ways to configure the navigation of your dashboard, head to [Navigation](../user-guides/navigation.md). Vizro doesn't end here, and we only covered the key features, but there is still much more to explore! You can learn: @@ -683,3 +630,12 @@ Vizro doesn't end here, and we only covered the key features, but there is still - How to add custom styling using [static assets](../user-guides/assets.md) such as custom css or JavaScript files. - How to use [Actions](../user-guides/actions.md) for example, for chart interaction or custom controls. - How to create dashboards from `yaml`, `dict` or `json` following the [dashboard guide](../user-guides/dashboard.md). + +[finalpage]: ../../assets/tutorials/dashboard/dashboard4.png +[finalpage1]: ../../assets/tutorials/dashboard/dashboard2.png +[finalpage2]: ../../assets/tutorials/dashboard/dashboard3.png +[firstpage1]: ../../assets/tutorials/dashboard/dashboard21.png +[firstpage2]: ../../assets/tutorials/dashboard/dashboard22.png +[firstpage3]: ../../assets/tutorials/dashboard/dashboard23.png +[firstpage4]: ../../assets/tutorials/dashboard/dashboard24.png +[secondpage]: ../../assets/tutorials/dashboard/dashboard3.png diff --git a/vizro-core/docs/pages/tutorials/first-dashboard.md b/vizro-core/docs/pages/tutorials/first-dashboard.md index 65fafd321..a33bb4521 100644 --- a/vizro-core/docs/pages/tutorials/first-dashboard.md +++ b/vizro-core/docs/pages/tutorials/first-dashboard.md @@ -29,22 +29,28 @@ Click on the **Run and edit this code in PyCafe** link below to live-edit the da ``` === "Result" - - [![FirstDash]][FirstDash] - - [FirstDash]: ../../assets/tutorials/dashboard/first-dashboard.png + [![FirstDash]][firstdash] + ## Can I break this code? + + When you click the link to "Edit live on PyCafe" the dashboard is running inside your browser. Any changes you make are local and you don't need to worry about breaking the code for others. Nobody else sees the changes you make unless you save a copy of the project as your own Vizro PyCafe project. + ## How can I make my own dashboards? + + You can use PyCafe to experiment with your own Vizro dashboards by dropping code onto a new project. Check out the [PyCafe documentation](https://py.cafe/docs/apps/vizro) for more information. If you need inspiration or a starting point, we make all our examples available for you to try out on PyCafe. Throughout our documentation, follow the "**Run and edit this code in PyCafe**" link below the code snippets to open them in PyCafe. ## Where next? + You are now ready to explore Vizro further, by working through the ["Explore Vizro" tutorial](explore-components.md) or by consulting the [how-to guides](../user-guides/dashboard.md). + +[firstdash]: ../../assets/tutorials/dashboard/first-dashboard.png diff --git a/vizro-core/docs/pages/user-guides/actions.md b/vizro-core/docs/pages/user-guides/actions.md index 3c811eb48..6a41ee25d 100644 --- a/vizro-core/docs/pages/user-guides/actions.md +++ b/vizro-core/docs/pages/user-guides/actions.md @@ -1,7 +1,6 @@ # How to use actions -This guide shows you how to use actions, an idea that is similar to [callbacks](https://dash.plotly.com/basic-callbacks) in `Dash`. -Many components of a dashboard (for example, [`Graph`][vizro.models.Graph] or [`Button`][vizro.models.Button]) have an optional `actions` argument, where you can enter the [`Action`][vizro.models.Action] model. +This guide shows you how to use actions, an idea that is similar to [callbacks](https://dash.plotly.com/basic-callbacks) in `Dash`. Many components of a dashboard (for example, [`Graph`][vizro.models.Graph] or [`Button`][vizro.models.Button]) have an optional `actions` argument, where you can enter the [`Action`][vizro.models.Action] model. By combining the [`Action`][vizro.models.Action] model with an action function, you can create complex dashboard interactions triggered by various events. @@ -12,22 +11,18 @@ There are already a few action functions you can reuse: ## Pre-defined actions -To attach an action to a component, you must enter the [`Action`][vizro.models.Action] model into the component's `action` argument. You can then -add a desired pre-defined action function into the `function` argument of the [`Action`][vizro.models.Action]. +To attach an action to a component, you must enter the [`Action`][vizro.models.Action] model into the component's `action` argument. You can then add a desired pre-defined action function into the `function` argument of the [`Action`][vizro.models.Action]. ??? note "Note on `Trigger`" - Currently each component has one pre-defined trigger property. A trigger property is an attribute of the component that triggers a configured action (for example, for the `Button` it is `n_click`). The below sections are guides on how to use pre-defined action functions. ### Export data -To enable downloading data, you can add the [`export_data`][vizro.actions.export_data] action function to the [`Button`][vizro.models.Button] component. -Hence, as a result, when a dashboard user now clicks the button, all data on the page will be downloaded. +To enable downloading data, you can add the [`export_data`][vizro.actions.export_data] action function to the [`Button`][vizro.models.Button] component. Hence, as a result, when a dashboard user now clicks the button, all data on the page will be downloaded. !!! example "`export_data`" - === "app.py" ```{.python pycafe-link} import vizro.models as vm @@ -61,60 +56,55 @@ Hence, as a result, when a dashboard user now clicks the button, all data on the Vizro().build(dashboard).run() ``` + === "app.yaml" ```yaml # Still requires a .py to add data to the data manager and parse YAML configuration # See yaml_version example pages: - components: - - type: graph - figure: - _target_: scatter - data_frame: iris - color: sepal_width - x: petal_length - y: sepal_length - - type: graph - figure: - _target_: histogram - data_frame: iris - color: species - x: petal_length - - type: button - text: Export data - id: export_data_button - actions: - - function: - _target_: export_data + - type: graph + figure: + _target_: scatter + data_frame: iris + color: sepal_width + x: petal_length + y: sepal_length + - type: graph + figure: + _target_: histogram + data_frame: iris + color: species + x: petal_length + - type: button + text: Export data + id: export_data_button + actions: + - function: + _target_: export_data title: Exporting ``` - === "Result" - [![Graph]][Graph] - - [Graph]: ../../assets/user_guides/actions/actions_export.png + === "Result" + [![Graph]][graph] !!! note - - Note that exported data only reflects the original dataset and any native data modifications defined with [`vm.Filter`](filters.md), [`vm.Parameter`](data.md/#parametrize-data-loading) or [`filter_interaction`](actions.md/#filter-data-by-clicking-on-chart) action. - Filters from the chart itself, such as ag-grid filters, are not included, and neither are other chart modifications, nor any data transformations in custom charts. + Note that exported data only reflects the original dataset and any native data modifications defined with [`vm.Filter`](filters.md), [`vm.Parameter`](data.md/#parametrize-data-loading) or [`filter_interaction`](actions.md/#filter-data-by-clicking-on-chart) action. Filters from the chart itself, such as ag-grid filters, are not included, and neither are other chart modifications, nor any data transformations in custom charts. ### Filter data by clicking on chart -To enable filtering when clicking on data in a source chart, you can add the -[`filter_interaction`][vizro.actions.filter_interaction] action function to the [`Graph`][vizro.models.Graph], -[`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid] components. -The [`filter_interaction`][vizro.actions.filter_interaction] is currently configured -to be triggered on click only. +To enable filtering when clicking on data in a source chart, you can add the [`filter_interaction`][vizro.actions.filter_interaction] action function to the [`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid] components. The [`filter_interaction`][vizro.actions.filter_interaction] is currently configured to be triggered on click only. To configure this chart interaction follow the steps below: -1. Add the action function to the source [`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid] -component and a list of IDs of the target charts into `targets`. +1. Add the action function to the source [`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid] component and a list of IDs of the target charts into `targets`. + ```py actions=[vm.Action(function=filter_interaction(targets=["scatter_relation_2007"]))] ``` -2. If the source chart is [`Graph`][vizro.models.Graph], enter the filter columns in the `custom_data` argument of the underlying source chart `function`. + +1. If the source chart is [`Graph`][vizro.models.Graph], enter the filter columns in the `custom_data` argument of the underlying source chart `function`. + ```py Graph(figure=px.scatter(..., custom_data=["continent"])) ``` @@ -128,7 +118,6 @@ Selecting a data point with a corresponding value of "Africa" in the continent c Here is an example of how to configure a chart interaction when the source is a [`Graph`][vizro.models.Graph] component. !!! example "Graph `filter_interaction`" - === "app.py" ```{.python pycafe-link} import vizro.models as vm @@ -171,50 +160,47 @@ Here is an example of how to configure a chart interaction when the source is a Vizro().build(dashboard).run() ``` + === "app.yaml" ```yaml # Still requires a .py to add data to the data manager and parse YAML configuration # See yaml_version example pages: - components: - - type: graph - figure: - _target_: box - data_frame: gapminder - color: continent - x: continent - y: lifeExp - custom_data: - - continent - actions: - - function: - _target_: filter_interaction - targets: - - scatter_relation_2007 - - type: graph - id: scatter_relation_2007 - figure: - _target_: scatter - data_frame: gapminder - color: continent - x: gdpPercap - y: lifeExp - size: pop + - type: graph + figure: + _target_: box + data_frame: gapminder + color: continent + x: continent + y: lifeExp + custom_data: + - continent + actions: + - function: + _target_: filter_interaction + targets: + - scatter_relation_2007 + - type: graph + id: scatter_relation_2007 + figure: + _target_: scatter + data_frame: gapminder + color: continent + x: gdpPercap + y: lifeExp + size: pop controls: - column: continent type: filter title: Filter interaction ``` - === "Result" - [![Graph2]][Graph2] - - [Graph2]: ../../assets/user_guides/actions/actions_filter_interaction.png + === "Result" + [![Graph2]][graph2] !!! note "`filter_interaction` with custom charts" - - If `filter_interaction` is assigned to a [custom chart](custom-charts.md), ensure that `custom_data` is an argument of the custom chart function, and that this argument is then passed to the underlying plotly function. - When then adding the custom chart in `vm.Graph`, ensure that `custom_data` is passed. + If `filter_interaction` is assigned to a [custom chart](custom-charts.md), ensure that `custom_data` is an argument of the custom chart function, and that this argument is then passed to the underlying plotly function. When then adding the custom chart in `vm.Graph`, ensure that `custom_data` is passed. ```py @capture("graph") @@ -227,11 +213,9 @@ Here is an example of how to configure a chart interaction when the source is a ``` - Here is an example of how to configure a chart interaction when the source is an [`AgGrid`][vizro.models.AgGrid] component. !!! example "AgGrid `filter_interaction`" - === "app.py" ```{.python pycafe-link} import vizro.models as vm @@ -271,57 +255,53 @@ Here is an example of how to configure a chart interaction when the source is an Vizro().build(dashboard).run() ``` + === "app.yaml" ```yaml # Still requires a .py to add data to the data manager and parse YAML configuration # See yaml_version example pages: - components: - - type: ag_grid - figure: - _target_: dash_ag_grid - data_frame: gapminder_2007 - actions: - - function: - _target_: filter_interaction - targets: - - scatter_relation_2007 - - type: graph - id: scatter_relation_2007 - figure: - _target_: scatter - data_frame: gapminder_2007 - color: continent - x: gdpPercap - y: lifeExp - size: pop + - type: ag_grid + figure: + _target_: dash_ag_grid + data_frame: gapminder_2007 + actions: + - function: + _target_: filter_interaction + targets: + - scatter_relation_2007 + - type: graph + id: scatter_relation_2007 + figure: + _target_: scatter + data_frame: gapminder_2007 + color: continent + x: gdpPercap + y: lifeExp + size: pop controls: - column: continent type: filter title: Filter interaction ``` - === "Result" - [![Table]][Table] - - [Table]: ../../assets/user_guides/actions/actions_table_filter_interaction.png + === "Result" + [![Table]][table] ### Customize pre-defined actions + Many pre-defined actions are customizable which helps to achieve a more specific goal. Refer to the [API reference][vizro.actions] for the options available. ## Custom actions -If you require an action that isn't available as a pre-defined option, you can create a custom action function. -Refer to our [user guide on custom actions](custom-actions.md) for more information. +If you require an action that isn't available as a pre-defined option, you can create a custom action function. Refer to our [user guide on custom actions](custom-actions.md) for more information. ## Chain actions -The `actions` parameter for the different screen components accepts a `list` of [`Action`][vizro.models.Action] models. -This means that it's possible to chain together a list of actions that are executed by triggering only one component. -The order of action execution is guaranteed, and the next action in the list will start executing only when the previous one is completed. +The `actions` parameter for the different screen components accepts a `list` of [`Action`][vizro.models.Action] models. This means that it's possible to chain together a list of actions that are executed by triggering only one component. The order of action execution is guaranteed, and the next action in the list will start executing only when the previous one is completed. !!! example "Actions chaining" - === "app.py" ```{.python pycafe-link extra-requirements="openpyxl"} import vizro.models as vm @@ -368,44 +348,49 @@ The order of action execution is guaranteed, and the next action in the list wil Vizro().build(dashboard).run() ``` + === "app.yaml" ```yaml pages: - components: - - type: graph - id: scatter - figure: - _target_: scatter - data_frame: iris - color: sepal_width - x: petal_length - y: sepal_length - - type: graph - id: hist - figure: - _target_: histogram - data_frame: iris - color: species - x: petal_length - - type: button - text: Export data - id: export_data_button - actions: - - function: - _target_: export_data - targets: - - scatter - - function: - _target_: export_data - targets: - - hist - file_format: xlsx + - type: graph + id: scatter + figure: + _target_: scatter + data_frame: iris + color: sepal_width + x: petal_length + y: sepal_length + - type: graph + id: hist + figure: + _target_: histogram + data_frame: iris + color: species + x: petal_length + - type: button + text: Export data + id: export_data_button + actions: + - function: + _target_: export_data + targets: + - scatter + - function: + _target_: export_data + targets: + - hist + file_format: xlsx controls: - type: filter column: species title: Exporting ``` + === "Result" - [![Graph3]][Graph3] + [![Graph3]][graph3] - [Graph3]: ../../assets/user_guides/actions/actions_chaining.png +[graph]: ../../assets/user_guides/actions/actions_export.png +[graph2]: ../../assets/user_guides/actions/actions_filter_interaction.png +[graph3]: ../../assets/user_guides/actions/actions_chaining.png +[table]: ../../assets/user_guides/actions/actions_table_filter_interaction.png diff --git a/vizro-core/docs/pages/user-guides/assets.md b/vizro-core/docs/pages/user-guides/assets.md index ae87f5527..87c79fb07 100644 --- a/vizro-core/docs/pages/user-guides/assets.md +++ b/vizro-core/docs/pages/user-guides/assets.md @@ -1,11 +1,8 @@ # How to add static assets -This guide shows you how to add static assets to your dashboard. Static assets are images that you would like to show in your dashboard, or custom CSS and JS files -with which you would like to enhance/change the appearance of your dashboard. +This guide shows you how to add static assets to your dashboard. Static assets are images that you would like to show in your dashboard, or custom CSS and JS files with which you would like to enhance/change the appearance of your dashboard. -To add images, custom CSS or JS files, create a folder named `assets` in the root of your app directory and insert your files. -Assets included in that folder are automatically served after serving Vizro's static files via the `external_stylesheets` and `external_scripts` arguments of [Dash](https://dash.plotly.com/external-resources#adding-external-css/javascript). -The user's `assets` folder thus always takes precedence. +To add images, custom CSS or JS files, create a folder named `assets` in the root of your app directory and insert your files. Assets included in that folder are automatically served after serving Vizro's static files via the `external_stylesheets` and `external_scripts` arguments of [Dash](https://dash.plotly.com/external-resources#adding-external-css/javascript). The user's `assets` folder thus always takes precedence. ```text title="Example folder structure" ├── app.py @@ -21,15 +18,11 @@ The user's `assets` folder thus always takes precedence. ``` !!! warning "Dash Bootstrap Themes" - - Note that Vizro is currently not compatible with [Dash Bootstrap Themes](https://dash-bootstrap-components.opensource.faculty.ai/docs/themes/). - Adding a Bootstrap stylesheet will have no visual effect on the [components](https://vizro.readthedocs.io/en/stable/pages/user_guides/components/) included in Vizro. - + Note that Vizro is currently not compatible with [Dash Bootstrap Themes](https://dash-bootstrap-components.opensource.faculty.ai/docs/themes/). Adding a Bootstrap stylesheet will have no visual effect on the [components](https://vizro.readthedocs.io/en/stable/pages/user_guides/components/) included in Vizro. ## Change the favicon -To change the default favicon (website icon appearing in the browser tab), add a file named `favicon.ico` to your `assets` folder. -For more information, see the [Dash documentation](https://dash.plotly.com/external-resources#changing-the-favicon). +To change the default favicon (website icon appearing in the browser tab), add a file named `favicon.ico` to your `assets` folder. For more information, see the [Dash documentation](https://dash.plotly.com/external-resources#changing-the-favicon). ## Add a logo image @@ -41,52 +34,36 @@ If an image named `logo.
-
- ## Header level 2
-
- ### Header level 3
-
- #### Header level 4
- type: card
- - text: |
- Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
-
- Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
-
- Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
-
- Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
- title: Paragraphs
- type: card
- - text: |
- >
- > A block quote is a long quotation, indented to create a separate block of text.
- >
- title: Block Quotes
- type: card
- - text: |
- * Item A
- * Sub Item 1
- * Sub Item 2
- * Item B
- title: Lists
- type: card
- - text: |
- This word will be *italic*
-
- This word will be **bold**
-
- This word will be _**bold and italic**_
- title: Emphasis
- type: card
- title: Customizing Text
+ - components:
+ - text: |
+ # Header level 1
+
+ ## Header level 2
+
+ ### Header level 3
+
+ #### Header level 4
+ type: card
+ - text: |
+ Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
+
+ Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
+
+ Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
+
+ Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
+ title: Paragraphs
+ type: card
+ - text: |
+ >
+ > A block quote is a long quotation, indented to create a separate block of text.
+ >
+ title: Block Quotes
+ type: card
+ - text: |
+ * Item A
+ * Sub Item 1
+ * Sub Item 2
+ * Item B
+ title: Lists
+ type: card
+ - text: |
+ This word will be *italic*
+
+ This word will be **bold**
+
+ This word will be _**bold and italic**_
+ title: Emphasis
+ type: card
+ title: Customizing Text
```
- === "Result"
- [![CardText]][CardText]
- [CardText]: ../../assets/user_guides/components/card_text.png
+ === "Result"
+ [![CardText]][cardtext]
### Place an image on a card
@@ -189,11 +185,10 @@ Images can be added to the `text` parameter by using the standard markdown synta
``
-An image ALT text offers a description to your image and serves as a text placeholder or to improve the
-accessibility of your app. Providing an image ALT text is optional.
+An image ALT text offers a description to your image and serves as a text placeholder or to improve the accessibility of your app. Providing an image ALT text is optional.
1. To use a relative Image URL, place an image of your choice into your `assets` folder first
-2. Use markdown to render your image by using one of the following syntax:
+1. Use markdown to render your image by using one of the following syntax:
- Relative Image URL: ``
- Absolute Image URL: ``
@@ -228,55 +223,50 @@ accessibility of your app. Providing an image ALT text is optional.
Run and edit this code in PyCafe
-
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - text: |
- 
+ - components:
+ - text: |
+ 
- Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
+ Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
- Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
+ Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
- Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
- title: My card with image!
- type: card
- title: Placing Images
+ Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
+ title: My card with image!
+ type: card
+ title: Placing Images
```
- === "Result"
- [![CardImageDefault]][CardImageDefault]
- [CardImageDefault]: ../../assets/user_guides/components/card_image_default.png
+ === "Result"
+ [![CardImageDefault]][cardimagedefault]
!!! note
-
- Note that inserting images using html is by default turned off by the `dcc.Markdown` to prevent users being exposed
- to cross-site scripting attacks. If you need to turn it on, a custom component would have to be created.
+ Note that inserting images using HTML is by default turned off by the `dcc.Markdown` to prevent users being exposed to cross-site scripting attacks. If you need to turn it on, a custom component would have to be created.
You might notice that the image is quite large. You'll find out how to style images in terms of their position and size in the next section.
-
### Style a card image
To change the size or position of the image, add a URL hash to your image like this:
``
-Note the added URL hash `#my-image`. Now create a CSS file placed in your `assets` folder
-and give an attribute selector to select images with that matching URL hash.
+Note the added URL hash `#my-image`. Now create a CSS file placed in your `assets` folder and give an attribute selector to select images with that matching URL hash.
!!! example "Card with styled image"
=== "images.css"
- ```css
- img[src*="#my-image"] {
- width: 120px;
- height: 120px;
- }
- ```
+ ```css
+ img[src*="#my-image"] {
+ width: 120px;
+ height: 120px;
+ }
+ ```
+
=== "app.py"
```py
import vizro.models as vm
@@ -313,23 +303,22 @@ and give an attribute selector to select images with that matching URL hash.
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - text: |
- 
+ - components:
+ - text: |
+ 
- Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
+ Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
- Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
+ Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
- Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
- title: My card with image!
- type: card
- title: Styling Images
+ Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
+ title: My card with image!
+ type: card
+ title: Styling Images
```
- === "Result"
- [![CardImageStyled]][CardImageStyled]
- [CardImageStyled]: ../../assets/user_guides/components/card_image_styled.png
+ === "Result"
+ [![CardImageStyled]][cardimagestyled]
Use the following pre-defined URL hashes in your image path to apply Vizro's default styling.
@@ -341,12 +330,13 @@ Use the following pre-defined URL hashes in your image path to apply Vizro's def
!!! example "Card with floating image"
=== "images.css"
- ```css
- img[src*="#my-image"] {
- width: 120px;
- height: 120px;
- }
- ```
+ ```css
+ img[src*="#my-image"] {
+ width: 120px;
+ height: 120px;
+ }
+ ```
+
=== "app.py"
```py
import vizro.models as vm
@@ -389,29 +379,28 @@ Use the following pre-defined URL hashes in your image path to apply Vizro's def
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - text: |
- 
+ - components:
+ - text: |
+ 
- Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
+ Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
- Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
+ Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
- Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
+ Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
- Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
+ Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
- Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
+ Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
- Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
- title: My card with floating image!
- type: card
- title: Floating Images
+ Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
+ title: My card with floating image!
+ type: card
+ title: Floating Images
```
- === "Result"
- [![CardImageFloating]][CardImageFloating]
- [CardImageFloating]: ../../assets/user_guides/components/card_image_floating.png
+ === "Result"
+ [![CardImageFloating]][cardimagefloating]
#### Card with icon
@@ -442,38 +431,34 @@ Use the following pre-defined URL hashes in your image path to apply Vizro's def
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - text: |
- 
+ - components:
+ - text: |
+ 
- ### Card Title
+ ### Card Title
- Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut fringilla dictum lacus eget fringilla.
- Maecenas in various nibh, quis venenatis nulla. Integer et libero ultrices, scelerisque velit sed.
- type: card
- title: Card with icon
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut fringilla dictum lacus eget fringilla.
+ Maecenas in various nibh, quis venenatis nulla. Integer et libero ultrices, scelerisque velit sed.
+ type: card
+ title: Card with icon
```
- === "Result"
- [![CardIcon]][CardIcon]
-
- [CardIcon]: ../../assets/user_guides/components/card_icon.png
+ === "Result"
+ [![CardIcon]][cardicon]
### Make an icon responsive to theme switch
-To make an icon responsive to the theme switch, override the value of the [`filter` CSS property](https://developer.mozilla.org/en-US/docs/Web/CSS/filter).
-The `filter` CSS property lets you add visual effects to elements using different functions. In our example, we're using the `--inverse-color` CSS variable from the Vizro theme.
-It uses the CSS `invert()` function to flip the color of the icon when you switch themes. Note that this only works if your initial icon has a white fill color. If your icon is not white, you can change its color by adding `fill="white"` to the SVG code.
-Assign the predefined CSS variable `--inverse-color` to the `filter` property of your selected icon.
+To make an icon responsive to the theme switch, override the value of the [`filter` CSS property](https://developer.mozilla.org/en-US/docs/Web/CSS/filter). The `filter` CSS property lets you add visual effects to elements using different functions. In our example, we're using the `--inverse-color` CSS variable from the Vizro theme. It uses the CSS `invert()` function to flip the color of the icon when you switch themes. Note that this only works if your initial icon has a white fill color. If your icon is not white, you can change its color by adding `fill="white"` to the SVG code. Assign the predefined CSS variable `--inverse-color` to the `filter` property of your selected icon.
```css
img[src*="#my-image"] {
- filter: var(--inverse-color);
+ filter: var(--inverse-color);
}
```
@@ -482,18 +467,15 @@ img[src*="#my-image"] {
### Create a navigation card
-This section describes how to use the [`Card`][vizro.models.Card] component to create a navigation card,
-enabling users to navigate to another page by clicking on the card area.
+This section describes how to use the [`Card`][vizro.models.Card] component to create a navigation card, enabling users to navigate to another page by clicking on the card area.
-For a button-style link navigation component, see the [separate guide on creating a link button](#create-a-link-button).
-To configure the navigation panel on the left hand side of the screen, refer to the
-[separate guide on navigation](navigation.md).
+For a button-style link navigation component, see the [separate guide on creating a link button](#create-a-link-button). To configure the navigation panel on the left hand side of the screen, refer to the [separate guide on navigation](navigation.md).
To create a navigation card:
1. Insert the [`Card`][vizro.models.Card] into the `components` argument of the [`Page`][vizro.models.Page].
-2. Pass your markdown text to the `Card.text`.
-3. Pass a relative or absolute URL to the `Card.href`.
+1. Pass your markdown text to the `Card.text`.
+1. Pass a relative or absolute URL to the `Card.href`.
!!! example "Navigation Card"
=== "app.py"
@@ -537,72 +519,65 @@ To create a navigation card:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - text: |
- ### Filters and parameters
-
- Leads to the first page on click
- href: /filters-and-parameters
- type: card
- - text: |
- ### Google - External Link
-
- Leads to an external link on click.
- href: https://google.com
- type: card
- title: Homepage
- - components:
- - figure:
- _target_: scatter
- color: sepal_width
- data_frame: iris
- x: sepal_length
- y: petal_width
- type: graph
- title: Filters and parameters
+ - components:
+ - text: |
+ ### Filters and parameters
+
+ Leads to the first page on click
+ href: /filters-and-parameters
+ type: card
+ - text: |
+ ### Google - External Link
+
+ Leads to an external link on click.
+ href: https://google.com
+ type: card
+ title: Homepage
+ - components:
+ - figure:
+ _target_: scatter
+ color: sepal_width
+ data_frame: iris
+ x: sepal_length
+ y: petal_width
+ type: graph
+ title: Filters and parameters
```
- === "Result"
- [![NavCard]][NavCard]
- [NavCard]: ../../assets/user_guides/components/nav_card.png
+ === "Result"
+ [![NavCard]][navcard]
If you now click on the card area, you should automatically be redirected to the relevant `href`.
!!! note
-
When using the [`Card`][vizro.models.Card], keep the following in mind:
- If the href given is a relative URL, it should match the `path` of the [`Page`][vizro.models.Page] that the [`Card`][vizro.models.Card] should navigate to.
- If the href given is an absolute link, it should start with `https://` or an equivalent protocol.
-
### Create a KPI card
-To create a KPI card, you can use the existing KPI card functions from [`vizro.figures`](../API-reference/figure-callables.md).
-Unlike the static text card `vm.Card`, a KPI card must be created using a figure function,
-which enables the text content of the KPI to change based on input from controls or actions.
+
+To create a KPI card, you can use the existing KPI card functions from [`vizro.figures`](../API-reference/figure-callables.md). Unlike the static text card `vm.Card`, a KPI card must be created using a figure function, which enables the text content of the KPI to change based on input from controls or actions.
For detailed examples on how to create a KPI card, refer to the [figure user guide on KPI cards](figure.md#key-performance-indicator-kpi-cards).
## Buttons
-The Button component is commonly used for interactive dashboard interactions
-such as form submissions, navigation links, and other action triggers.
-
-To add a [`Button`][vizro.models.Button], insert it into the `components` argument of the
-[`Page`][vizro.models.Page].
+The Button component is commonly used for interactive dashboard interactions such as form submissions, navigation links, and other action triggers.
+To add a [`Button`][vizro.models.Button], insert it into the `components` argument of the [`Page`][vizro.models.Page].
### Customize button text
You can configure the `text` argument to alter the display text of the [`Button`][vizro.models.Button].
!!! example "Customize text"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -616,26 +591,24 @@ You can configure the `text` argument to alter the display text of the [`Button`
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- components:
- - type: button
- text: I'm a button!
+ - type: button
+ text: I'm a button!
title: Button with text
```
- === "Result"
- [![ButtonText]][ButtonText]
-
- [ButtonText]: ../../assets/user_guides/components/button_text.png
+ === "Result"
+ [![ButtonText]][buttontext]
### Create a link button
-To navigate to a different page using a button with an anchor tag, assign an absolute or relative URL to the
-`Button.href`.
+To navigate to a different page using a button with an anchor tag, assign an absolute or relative URL to the `Button.href`.
```python
import vizro.models as vm
@@ -645,16 +618,11 @@ vm.Button(text="Leave us a star! ⭐", href="https://github.com/mckinsey/vizro")
### Attach an action
-You can use the [`Button`][vizro.models.Button] to trigger predefined action functions, such as exporting data.
-To explore the available options for [`Actions`][vizro.models.Action], refer to our [API reference][vizro.actions].
-Use the `Button.actions` argument to specify which action function executes when the button is clicked.
-
-The example below demonstrates how to configure a button to export the filtered data of a target chart using the
-[export_data][vizro.actions.export_data] action function.
+You can use the [`Button`][vizro.models.Button] to trigger predefined action functions, such as exporting data. To explore the available options for [`Actions`][vizro.models.Action], refer to our [API reference][vizro.actions]. Use the `Button.actions` argument to specify which action function executes when the button is clicked.
+The example below demonstrates how to configure a button to export the filtered data of a target chart using the [export_data][vizro.actions.export_data] action function.
!!! example "Button with action"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -690,29 +658,30 @@ The example below demonstrates how to configure a button to export the filtered
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- components:
- - figure:
- _target_: scatter
- x: sepal_width
- y: sepal_length
- color: species
- size: petal_length
- data_frame: iris
- id: scatter_chart
- type: graph
- - type: button
- text: Export data
- id: export_data
- actions:
- - function:
- _target_: export_data
- targets:
- - scatter_chart
+ - figure:
+ _target_: scatter
+ x: sepal_width
+ y: sepal_length
+ color: species
+ size: petal_length
+ data_frame: iris
+ id: scatter_chart
+ type: graph
+ - type: button
+ text: Export data
+ id: export_data
+ actions:
+ - function:
+ _target_: export_data
+ targets:
+ - scatter_chart
controls:
- column: species
selector:
@@ -728,14 +697,13 @@ The example below demonstrates how to configure a button to export the filtered
- [1]
title: My first page
```
- === "Result"
- [![Button]][Button]
- [Button]: ../../assets/user_guides/components/button.png
+ === "Result"
+ [![Button]][button]
### Use as a control
-The [`Button`][vizro.models.Button] component is currently reserved to be used inside the main panel (right-side) of the dashboard.
-However, there might be use cases where one would like to place the `Button` inside the control panel (left-side) with the other controls.
+
+The [`Button`][vizro.models.Button] component is currently reserved to be used inside the main panel (right-side) of the dashboard. However, there might be use cases where one would like to place the `Button` inside the control panel (left-side) with the other controls.
In this case, follow the user-guide outlined for [creating custom components](custom-components.md) and manually add the `Button` as a valid type to the `controls` argument by running the following lines before your dashboard configurations:
@@ -748,3 +716,13 @@ vm.Page.add_type("controls", vm.Button)
# Add dashboard configurations below
...
```
+
+[button]: ../../assets/user_guides/components/button.png
+[buttontext]: ../../assets/user_guides/components/button_text.png
+[card]: ../../assets/user_guides/components/card.png
+[cardicon]: ../../assets/user_guides/components/card_icon.png
+[cardimagedefault]: ../../assets/user_guides/components/card_image_default.png
+[cardimagefloating]: ../../assets/user_guides/components/card_image_floating.png
+[cardimagestyled]: ../../assets/user_guides/components/card_image_styled.png
+[cardtext]: ../../assets/user_guides/components/card_text.png
+[navcard]: ../../assets/user_guides/components/nav_card.png
diff --git a/vizro-core/docs/pages/user-guides/components.md b/vizro-core/docs/pages/user-guides/components.md
index 106bf6a0b..45ea5a123 100755
--- a/vizro-core/docs/pages/user-guides/components.md
+++ b/vizro-core/docs/pages/user-guides/components.md
@@ -1,8 +1,6 @@
# Components
-The [`Page`][vizro.models.Page] model accepts the `components` argument, where you can enter any of the components
-listed below to fill your dashboard with visuals.
-
+The [`Page`][vizro.models.Page] model accepts the `components` argument, where you can enter any of the components listed below to fill your dashboard with visuals.
@@ -38,7 +36,6 @@ listed below to fill your dashboard with visuals.
[:octicons-arrow-right-24: View user guide](card-button.md)
-
- :octicons-table-16:{ .lg .middle } __Containers__
---
diff --git a/vizro-core/docs/pages/user-guides/container.md b/vizro-core/docs/pages/user-guides/container.md
index c7e327c5f..2f379709e 100755
--- a/vizro-core/docs/pages/user-guides/container.md
+++ b/vizro-core/docs/pages/user-guides/container.md
@@ -2,30 +2,22 @@
This guide shows you how to use containers to group your components into sections and subsections within the page.
-A [`Container`][vizro.models.Container] complements the idea of a [`Page`][vizro.models.Page], and the two models have almost identical arguments.
- [`Page.layout`](layouts.md) offers a way to structure the overall layout of the page, and a `Container` enables more granular control within a specific section of that page.
+A [`Container`][vizro.models.Container] complements the idea of a [`Page`][vizro.models.Page], and the two models have almost identical arguments. [`Page.layout`](layouts.md) offers a way to structure the overall layout of the page, and a `Container` enables more granular control within a specific section of that page.
-While there is currently no clear difference in rendering, extra functionality will be added to the `Container` soon (including controls specific to that container),
-enhancing the ability to manage related components.
+While there is currently no clear difference in rendering, extra functionality will be added to the `Container` soon (including controls specific to that container), enhancing the ability to manage related components.
!!! note "Displaying multiple containers inside Tabs"
-
An alternative way to display multiple containers on one page is to place them inside [Tabs](tabs.md).
- [`Tabs`][vizro.models.Tabs] organize and separate groups of related content in a dashboard, letting users switch between different sections or views.
- They are a way of putting multiple containers into the same screen space, and letting the user switch between them.
+ [`Tabs`][vizro.models.Tabs] organize and separate groups of related content in a dashboard, letting users switch between different sections or views. They are a way of putting multiple containers into the same screen space, and letting the user switch between them.
{ width="500" }
-
-
## When to use containers
-In general, any arbitrarily granular layout can already be achieved by [using `Page.layout`](layouts.md) alone and is our
-recommended approach if you want to arrange components on a page with consistent row and/or column spacing.
-`Page.layout` has a `grid` argument that sets the overall layout of the page.
-`Container.layout` also has a `grid` argument. This enables you to insert a further `grid` into a component's space on the page,
-enabling more granular control by breaking the overall page grid into subgrids.
+In general, any arbitrarily granular layout can already be achieved by [using `Page.layout`](layouts.md) alone and is our recommended approach if you want to arrange components on a page with consistent row and/or column spacing.
+
+`Page.layout` has a `grid` argument that sets the overall layout of the page. `Container.layout` also has a `grid` argument. This enables you to insert a further `grid` into a component's space on the page, enabling more granular control by breaking the overall page grid into subgrids.
Here are a few cases where you might want to use a `Container` instead of `Page.layout`:
@@ -34,14 +26,14 @@ Here are a few cases where you might want to use a `Container` instead of `Page.
- If you want different row and column spacing between subgrids
- If you want to apply controls to selected subgrids (will be supported soon)
-
## Basic containers
+
To add a [`Container`][vizro.models.Container] to your page, do the following:
1. Insert the `Container` into the `components` argument of the [`Page`][vizro.models.Page]
-2. Set a `title` for your `Container`
-3. Configure your `components`, [read the overview page for various options](components.md)
-4. (optional) Configure your `layout`, see [the guide on `Layout`](layouts.md)
+1. Set a `title` for your `Container`
+1. Configure your `components`, [read the overview page for various options](components.md)
+1. (optional) Configure your `layout`, see [the guide on `Layout`](layouts.md)
!!! example "Container"
=== "app.py"
@@ -105,7 +97,7 @@ To add a [`Container`][vizro.models.Container] to your page, do the following:
```
1. Note that the `Page.layout` argument is not specified here and will therefore defaults to `[[0], [1]]`, meaning the containers will be **vertically stacked** down the page in one column.
- 2. **Horizontally stack** the components side-by-side inside this `Container` in one row.
+ 1. **Horizontally stack** the components side-by-side inside this `Container` in one row.
=== "app.yaml"
```yaml
@@ -149,27 +141,20 @@ To add a [`Container`][vizro.models.Container] to your page, do the following:
title: Container II
title: Containers
```
- === "Result"
- [![Container]][Container]
- [Container]: ../../assets/user_guides/components/containers.png
+ === "Result"
+ [![Container]][container]
Note that an almost identical layout can also be achieved using solely the [`Page.layout`](layouts.md) by configuring the `Page.layout` as `vm.Layout(grid = [[0, 1], [2, 2]])`.
## Nested containers
-Containers can be nested, providing a hierarchical structure for organizing components.
-This nesting capability enables users to create more complex layouts and manage related components at any level of granularity.
+
+Containers can be nested, providing a hierarchical structure for organizing components. This nesting capability enables users to create more complex layouts and manage related components at any level of granularity.
To create nested containers, add a `Container` to the `components` argument of another `Container`.
```python title="Example"
-vm.Container(
- title="Parent Container",
- components=[
- vm.Container(
- title="Child Container",
- components=[vm.Button()]
- )
- ]
-)
+vm.Container(title="Parent Container", components=[vm.Container(title="Child Container", components=[vm.Button()])])
```
+
+[container]: ../../assets/user_guides/components/containers.png
diff --git a/vizro-core/docs/pages/user-guides/custom-actions.md b/vizro-core/docs/pages/user-guides/custom-actions.md
index e5fa3afd8..2fb66cd2c 100644
--- a/vizro-core/docs/pages/user-guides/custom-actions.md
+++ b/vizro-core/docs/pages/user-guides/custom-actions.md
@@ -1,17 +1,16 @@
# How to create custom actions
-This guide demonstrates the usage of custom actions, an idea that shares similarities with, but is not identical to [callbacks](https://dash.plotly.com/basic-callbacks) in `Dash`.
-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.
+This guide demonstrates the usage of custom actions, an idea that shares similarities with, but is not identical to [callbacks](https://dash.plotly.com/basic-callbacks) in `Dash`. 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.
+
## Simple custom action
Custom actions enable you to implement your own action function. Simply do the following:
1. define a function
-2. decorate it with the `@capture("action")` decorator
-3. add it as a `function` argument inside the [`Action`][vizro.models.Action] model
+1. decorate it with the `@capture("action")` decorator
+1. add it as a `function` argument inside the [`Action`][vizro.models.Action] model
The following example shows how to create a custom action that postpones execution of the next action in the chain for `t` seconds.
@@ -58,27 +57,24 @@ The following example shows how to create a custom action that postpones executi
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
- ```yaml
- # Custom actions are currently only possible via Python configuration
- ```
-
+ Custom actions are currently only possible via Python configuration.
+
## Interact with inputs and outputs
+
When a custom action needs to interact with the dashboard, it is possible to define `inputs` and `outputs` for the custom action.
-- `inputs` represents dashboard component properties whose values are passed to the custom action function as arguments.
-It is a list of strings in the format `"."` (for example, `"my_selector.value`").
-- `outputs` represents dashboard component properties corresponding to the custom action function return value(s).
-Similar to `inputs`, it is a list of strings in the format `"."` (for example, `"my_card.children"`).
+- `inputs` represents dashboard component properties whose values are passed to the custom action function as arguments. It is a list of strings in the format `"."` (for example, `"my_selector.value`").
+- `outputs` represents dashboard component properties corresponding to the custom action function return value(s). Similar to `inputs`, it is a list of strings in the format `"."` (for example, `"my_card.children"`).
### Example of `value` as input
-The following example shows a custom action that takes the `value` of the `vm.RadioItem` and returns it inside a
-[`Card`][vizro.models.Card] component.
-!!! example "Display `value` in Card"
+The following example shows a custom action that takes the `value` of the `vm.RadioItem` and returns it inside a [`Card`][vizro.models.Card] component.
+!!! example "Display `value` in Card"
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -113,23 +109,18 @@ The following example shows a custom action that takes the `value` of the `vm.Ra
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
- === "app.yaml"
- ```yaml
- # Custom actions are currently only possible via Python configuration
- ```
- === "Result"
- [![ValueAction]][ValueAction]
- [ValueAction]: ../../assets/user_guides/custom_actions/value_as_input.png
+ === "app.yaml"
+ Custom actions are currently only possible via Python configuration.
+ === "Result"
+ [![ValueAction]][valueaction]
### Example of `clickData` as input
-The following example shows how to create a custom action that shows the `clickData` of a chart in a
-[`Card`][vizro.models.Card] component. For further information on the structure and content of the `clickData`
-property, refer to the Dash documentation on [interactive visualizations](https://dash.plotly.com/interactive-graphing).
-!!! example "Display `clickData` in Card"
+The following example shows how to create a custom action that shows the `clickData` of a chart in a [`Card`][vizro.models.Card] component. For further information on the structure and content of the `clickData` property, refer to the Dash documentation on [interactive visualizations](https://dash.plotly.com/interactive-graphing).
+!!! example "Display `clickData` in Card"
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -173,21 +164,18 @@ property, refer to the Dash documentation on [interactive visualizations](https:
```
1. Just as for any Python function, the names of the arguments `show_species` and `points_data` are arbitrary and do not need to match on to the names of `inputs` in any particular way.
- 2. We _bind_ (set) the argument `show_species` to the value `True` in the initial specification of the `function` field. These are static values that are fixed when the dashboard is _built_.
- 3. The content of `inputs` will "fill in the gaps" by setting values for the remaining unbound arguments in `my_custom_action`. Here there is one such argument, named `points_data`. Values for these are bound _dynamically at runtime_ to reflect the live state of your dashboard.
+ 1. We _bind_ (set) the argument `show_species` to the value `True` in the initial specification of the `function` field. These are static values that are fixed when the dashboard is _built_.
+ 1. The content of `inputs` will "fill in the gaps" by setting values for the remaining unbound arguments in `my_custom_action`. Here there is one such argument, named `points_data`. Values for these are bound _dynamically at runtime_ to reflect the live state of your dashboard.
+
=== "app.yaml"
- ```yaml
- # Custom actions are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomAction]][CustomAction]
+ Custom actions are currently only possible via Python configuration.
- [CustomAction]: ../../assets/user_guides/custom_actions/clickdata_as_input.png
+ === "Result"
+ [![CustomAction]][customaction]
## Multiple return values
-The return value of the custom action function is propagated to the dashboard components that are defined in the `outputs` argument of the [`Action`][vizro.models.Action] model.
-If there is a single `output` defined then the function return value is directly assigned to the component property.
-If there are multiple `outputs` defined then the return value is iterated through and each part is assigned to each component property given in `outputs` in turn. This behavior is identical to Python's flexibility in managing multiple return values.
+
+The return value of the custom action function is propagated to the dashboard components that are defined in the `outputs` argument of the [`Action`][vizro.models.Action] model. If there is a single `output` defined then the function return value is directly assigned to the component property. If there are multiple `outputs` defined then the return value is iterated through and each part is assigned to each component property given in `outputs` in turn. This behavior is identical to Python's flexibility in managing multiple return values.
!!! example "Multiple return values"
=== "app.py"
@@ -246,17 +234,17 @@ If there are multiple `outputs` defined then the return value is iterated throug
```
1. `my_custom_action` returns two values (which will be in Python tuple).
- 2. These values are assigned to the `outputs` in the same order.
- === "app.yaml"
- ```yaml
- # Custom actions are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomAction2]][CustomAction2]
+ 1. These values are assigned to the `outputs` in the same order.
- [CustomAction2]: ../../assets/user_guides/custom_actions/custom_action_multiple_return_values.png
+ === "app.yaml"
+ Custom actions are currently only possible via Python configuration.
+ === "Result"
+ [![CustomAction2]][customaction2]
!!! warning
+ Note that users of this package are responsible for the content of any custom action function that they write. Take care to avoid leaking any sensitive information or exposing to any security threat during implementation. You should always [treat the content of user input as untrusted](https://community.plotly.com/t/writing-secure-dash-apps-community-thread/54619).
- Note that users of this package are responsible for the content of any custom action function that they write - especially with regard to leaking any sensitive information or exposing to any security threat during implementation. You should always [treat the content of user input as untrusted](https://community.plotly.com/t/writing-secure-dash-apps-community-thread/54619).
+[customaction]: ../../assets/user_guides/custom_actions/clickdata_as_input.png
+[customaction2]: ../../assets/user_guides/custom_actions/custom_action_multiple_return_values.png
+[valueaction]: ../../assets/user_guides/custom_actions/value_as_input.png
diff --git a/vizro-core/docs/pages/user-guides/custom-charts.md b/vizro-core/docs/pages/user-guides/custom-charts.md
index cb26614c8..1b77d0869 100644
--- a/vizro-core/docs/pages/user-guides/custom-charts.md
+++ b/vizro-core/docs/pages/user-guides/custom-charts.md
@@ -1,9 +1,9 @@
# 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 graphs](graph.md).
+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 graphs](graph.md).
## When to use a custom chart
+
In general, you should use the custom chart decorator `@capture("graph")` if your plotly chart needs any post-update calls or customization. For example:
- You want to use any of the post figure update calls by `plotly` such as `update_layout`, `update_xaxes`, `update_traces` (for more details, see the docs on [plotly's update calls](https://plotly.com/python/creating-and-updating-figures/#other-update-methods))
@@ -12,11 +12,10 @@ In general, you should use the custom chart decorator `@capture("graph")` if you
## Steps to create a custom chart
1. Define a function that returns a `go.Figure()`.
-2. Decorate it with `@capture("graph")`.
-3. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
-4. The visualization should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments
-will not react to dashboard controls such as [`Filter`](filters.md).
-5. Pass your function to the `figure` argument of the [`Graph`][vizro.models.Graph] model.
+1. Decorate it with `@capture("graph")`.
+1. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
+1. The visualization should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments will not react to dashboard controls such as [`Filter`](filters.md).
+1. Pass your function to the `figure` argument of the [`Graph`][vizro.models.Graph] model.
The minimal example below can be used as a base to build more sophisticated charts.
@@ -39,12 +38,10 @@ To alter the data in the `data_frame` argument, consider using a [Filter](filter
## Enhanced `plotly.express` chart with reference line
-The below examples shows a case where we enhance an existing `plotly.express` chart. We add a new argument (`hline`), that is used to draw a grey reference line at the height determined by the value of `hline`. The important thing to note is that we then
-add a `Parameter` that enables the dashboard user to interact with the argument, and hence move the line in this case. See the `Result` tab for an animation.
+The below examples shows a case where we enhance an existing `plotly.express` chart. We add a new argument (`hline`), that is used to draw a grey reference line at the height determined by the value of `hline`. The important thing to note is that we then add a `Parameter` that enables the dashboard user to interact with the argument, and hence move the line in this case. See the `Result` tab for an animation.
!!! example "Custom `plotly.express` scatter chart with a `Parameter`"
=== "app.py"
-
```{.python pycafe-link}
import vizro.models as vm
import vizro.plotly.express as px
@@ -86,17 +83,14 @@ add a `Parameter` that enables the dashboard user to interact with the argument,
Vizro().build(dashboard).run()
```
- 1. Note that arguments of the custom chart can be parametrized. Here we choose to parametrize the `hline` argument (see below).
- 2. Here we parametrize the `hline` argument, but any other argument can be parametrized as well. Since there is complete flexibility regarding what can be derived from such arguments, the dashboard user has a wide range of customization options.
- === "app.yaml"
- ```yaml
- # Custom charts are currently only possible via Python configuration
- ```
- === "Result"
- [![Graph2]][Graph2]
+ 1. Note that arguments of the custom chart can be parametrized. Here we choose to parametrize the `hline` argument (see below).
+ 1. Here we parametrize the `hline` argument, but any other argument can be parametrized as well. Since there is complete flexibility regarding what can be derived from such arguments, the dashboard user has a wide range of customization options.
- [Graph2]: ../../assets/user_guides/custom_charts/custom_chart_showcase_parameter.gif
+ === "app.yaml"
+ Custom charts are currently only possible via Python configuration.
+ === "Result"
+ [![Graph2]][graph2]
## New Waterfall chart based on `go.Figure()`
@@ -104,7 +98,6 @@ The below examples shows a more involved use-case. We create and style a waterfa
!!! example "Custom `go.Figure()` waterfall chart with a `Parameter`"
=== "app.py"
-
```{.python pycafe-link}
import pandas as pd
import plotly.graph_objects as go
@@ -162,10 +155,10 @@ The below examples shows a more involved use-case. We create and style a waterfa
```
=== "app.yaml"
- ```yaml
- # Custom charts are currently only possible via Python configuration
- ```
+ Custom charts are currently only possible via Python configuration.
+
=== "Result"
- [![Graph3]][Graph3]
+ [![Graph3]][graph3]
- [Graph3]: ../../assets/user_guides/custom_charts/custom_chart_waterfall.png
+[graph2]: ../../assets/user_guides/custom_charts/custom_chart_showcase_parameter.gif
+[graph3]: ../../assets/user_guides/custom_charts/custom_chart_waterfall.png
diff --git a/vizro-core/docs/pages/user-guides/custom-css.md b/vizro-core/docs/pages/user-guides/custom-css.md
index dd2d22275..d5bc5f7dc 100755
--- a/vizro-core/docs/pages/user-guides/custom-css.md
+++ b/vizro-core/docs/pages/user-guides/custom-css.md
@@ -1,25 +1,20 @@
# Customizing Vizro dashboard CSS
-Vizro is opinionated about visual formatting, and some elements, such as the layout of the navigation and controls,
-are fixed. You can customize some settings such as background colors, fonts, and other styles via CSS overrides.
+Vizro is opinionated about visual formatting, and some elements, such as the layout of the navigation and controls, are fixed. You can customize some settings such as background colors, fonts, and other styles via CSS overrides.
To make customizations, you need to:
1. **Add a CSS file to your `assets` folder**. Refer to our user guide on [adding static assets](assets.md#how-to-add-static-assets).
-2. **Identify the correct CSS selector** for the component you want to style.
-3. **Change the relevant CSS properties** in your CSS file.
-
-
+1. **Identify the correct CSS selector** for the component you want to style.
+1. **Change the relevant CSS properties** in your CSS file.
## Introduction to Vizro CSS
+
For a short introduction to CSS, we recommend reading this article: [Get Started with CSS in 5 Minutes](https://www.freecodecamp.org/news/get-started-with-css-in-5-minutes-e0804813fc3e/).
-For a more comprehensive tutorial, refer to the [W3Schools CSS tutorial](https://www.w3schools.com/css/default.asp).
-The entire tutorial is beneficial, but the section on [CSS selectors](https://www.w3schools.com/css/css_selectors.asp)
-will be particularly useful.
+For a more comprehensive tutorial, refer to the [W3Schools CSS tutorial](https://www.w3schools.com/css/default.asp). The entire tutorial is beneficial, but the section on [CSS selectors](https://www.w3schools.com/css/css_selectors.asp) will be particularly useful.
-In Vizro, the CSS file is read in as an external stylesheet. The most common way of applying any styling to
-Vizro is therefore through the use of CSS selectors:
+In Vizro, the CSS file is read in as an external stylesheet. The most common way of applying any styling to Vizro is therefore through the use of CSS selectors:
- **Element Selector**: Applies the style to all elements inside the Vizro app.
@@ -33,8 +28,7 @@ Vizro is therefore through the use of CSS selectors:
}
```
-- **Class selector:** Targets all elements with the given class for styling. All CSS classes must be preceded with a
-`.` symbol.
+- **Class selector:** Targets all elements with the given class for styling. All CSS classes must be preceded with a `.` symbol.
```
.card {
@@ -50,30 +44,25 @@ Vizro is therefore through the use of CSS selectors:
}
```
-
## Identify the correct CSS selector
Use Chrome DevTools or a similar tool (Web Inspector, Web Developer Tools, etc.) to inspect the HTML document in your browser.
-1. **Open DevTools:** In Google Chrome, right-click on the app and select "Inspect" from the context menu. This opens the
-HTML document of your Vizro app.
+1. **Open DevTools:** In Google Chrome, right-click on the app and select "Inspect" from the context menu. This opens the HTML document of your Vizro app.
-
-2. **Select an element:** Suppose you want to change the background color of your cards. Click the
-"Select an element in the page to inspect it" icon in the top left corner of the inspect panel.
+1. **Select an element:** Suppose you want to change the background color of your cards. Click the "Select an element in the page to inspect it" icon in the top left corner of the inspect panel.
-3. **Find the HTML Block:** Hover over the component you want to style. The corresponding HTML block will be
-highlighted in the HTML document.
+1. **Find the HTML Block:** Hover over the component you want to style. The corresponding HTML block will be highlighted in the HTML document.
Notice that the selected HTML block corresponds to the container of the card and has a CSS class, here it is `card`.
-4. **Apply CSS:** Use this CSS class to style the card component. In your CSS file, you can write:
+1. **Apply CSS:** Use this CSS class to style the card component. In your CSS file, you can write:
```
.card {
@@ -83,25 +72,25 @@ highlighted in the HTML document.
This changes the background color for any HTML element with the `card` class.
-**Tip:** You can also test your CSS live by editing the CSS attributes in the "Elements" panel.
-For example, temporarily add `background: blue;`. Note that this change will be lost upon reloading the page.
+**Tip:** You can also test your CSS live by editing the CSS attributes in the "Elements" panel. For example, temporarily add `background: blue;`. Note that this change will be lost upon reloading the page.
-
## CSS overwrites
### Overwrite CSS globally
-To overwrite any global CSS property, you need to target the element selector and place your CSS file with the
-overwrites in the `assets` folder.
+
+To overwrite any global CSS property, you need to target the element selector and place your CSS file with the overwrites in the `assets` folder.
!!! example "Overwrite CSS globally"
=== "my_css_file.css"
- ```css
- h1, h2 {
- color: hotpink;
- }
- ```
+ ```css
+ h1,
+ h2 {
+ color: hotpink;
+ }
+ ```
+
=== "app.py"
```py
import os
@@ -134,44 +123,41 @@ overwrites in the `assets` folder.
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # This is an tag
+ - components:
+ - text: |
+ # This is an tag
- ## This is an tag
+ ## This is an tag
- ###### This is an tag
- type: card
- title: Changing the header color
+ ###### This is an tag
+ type: card
+ title: Changing the header color
```
- === "Result"
- [![AssetsCSS]][AssetsCSS]
-
- [AssetsCSS]: ../../assets/user_guides/assets/css_change.png
+ === "Result"
+ [![AssetsCSS]][assetscss]
### Overwrite CSS for selected pages
-To style components for a specific page, use the page's `id` in the CSS selectors. By default, this is the
-[same as the page `title`](pages.md), but such a value might not be a valid CSS identifier.
-A suitable `id` must be unique across all models in the dashboard and should contain only alphanumeric
-characters, hyphens (`-`) and underscores (`_`). In particular, note that spaces are _not_ allowed.
+To style components for a specific page, use the page's `id` in the CSS selectors. By default, this is the [same as the page `title`](pages.md), but such a value might not be a valid CSS identifier.
+
+A suitable `id` must be unique across all models in the dashboard and should contain only alphanumeric characters, hyphens (`-`) and underscores (`_`). In particular, note that spaces are _not_ allowed.
Suppose you want to hide the page title on one page only. Here's how you can achieve this:
1. Give a valid `id` to the `Page`, for example `Page(id="page-with-hidden-title", title="Page with hidden title", ...)`.
-2. Identify the CSS class or CSS `id` you need to target. To hide the page title, you need to hide the parent container with the id `right-header`.
-3. Use the `id` to hide the content.
-4. Add your custom css file to the `assets` folder.
-
+1. Identify the CSS class or CSS `id` you need to target. To hide the page title, you need to hide the parent container with the id `right-header`.
+1. Use the `id` to hide the content.
+1. Add your custom css file to the `assets` folder.
!!! example "Hide page title on selected pages"
=== "my_css_file.css"
- ```css
- #page-with-hidden-title #right-header {
- display: none;
- }
- ```
+ ```css
+ #page-with-hidden-title #right-header {
+ display: none;
+ }
+ ```
+
=== "app.py"
```py
import vizro.models as vm
@@ -199,25 +185,24 @@ Suppose you want to hide the page title on one page only. Here's how you can ach
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Placeholder
- type: card
- title: Page with hidden title
- id: page-with-hidden-title
- - components:
- - text: |
- # Placeholder
- type: card
- title: Page with shown title
+ - components:
+ - text: |
+ # Placeholder
+ type: card
+ title: Page with hidden title
+ id: page-with-hidden-title
+ - components:
+ - text: |
+ # Placeholder
+ type: card
+ title: Page with shown title
```
- === "Result"
- [![PageTitle]][PageTitle]
-
- [PageTitle]: ../../assets/user_guides/assets/css_page_title.png
+ === "Result"
+ [![PageTitle]][pagetitle]
### Overwrite CSS for selected components
+
To adjust CSS properties for specific components, such as altering the appearance of a selected [`Card`][vizro.models.Card] rather than all Cards, you need to supply an `id` to the component you want to style.
Let's say we want to change the `background-color` and `color` of a specific `Card`.
@@ -225,41 +210,43 @@ Let's say we want to change the `background-color` and `color` of a specific `Ca
Here's how you can do it:
1. Assign a unique `id` to the relevant `Card`, for example: `Card(id="custom-card", ...)`
-2. Run your dashboard and open it in your browser
-3. View the HTML document to find the appropriate CSS class or element you need to target, as explained in the section
-on [identifying the correct CSS selector](#identify-the-correct-css-selector).
+1. Run your dashboard and open it in your browser
+1. View the HTML document to find the appropriate CSS class or element you need to target, as explained in the section on [identifying the correct CSS selector](#identify-the-correct-css-selector).
-It's essential to understand the relationship between the targeted CSS class or element and the component assigned
-`id`, for example:
+It's essential to understand the relationship between the targeted CSS class or element and the component assigned `id`, for example:
-```html title="HTML structure of a `Card`"
+
+```html title="HTML structure of a card"
-
- Lorem ipsum dolor sit amet consectetur adipisicing elit.
-
+
+
+ Lorem ipsum dolor sit amet consectetur adipisicing elit.
+
+
```
-
-* **Main element with `id`:** There is a `` with our `id="custom-card"`.
-* **Parent element:** That `` is wrapped inside a parent `` with the class name `"card"`. This is the element we need to target to change the background color.
-* **Child element:** The card text is wrapped inside a `` that is a child of the `
` with our `id`. This is the element we need to target to change the font color.
+
+- **Main element with `id`:** There is a `` with our `id="custom-card"`.
+- **Parent element:** That `` is wrapped inside a parent `` with the class name `"card"`. This is the element we need to target to change the background color.
+- **Child element:** The card text is wrapped inside a `` that is a child of the `
` with our `id`. This is the element we need to target to change the font color.
!!! example "Customizing CSS properties in selective components"
=== "my_css_file.css"
- ```css
- /* Apply styling to parent */
- .card:has(#custom-card) {
- background-color: white;
- }
+ ```css
+ /* Apply styling to parent */
+ .card:has(#custom-card) {
+ background-color: white;
+ }
+
+ /* Apply styling to child */
+ #custom-card p {
+ color: black;
+ }
+ ```
- /* Apply styling to child */
- #custom-card p {
- color: black;
- }
- ```
=== "app.py"
```py
import vizro.models as vm
@@ -285,77 +272,65 @@ It's essential to understand the relationship between the targeted CSS class or
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- Lorem ipsum dolor sit amet consectetur adipisicing elit.
- type: card
- id: custom-card
- - text: |
- Lorem ipsum dolor sit amet consectetur adipisicing elit.
- type: card
- title: Changing the card color
+ - components:
+ - text: |
+ Lorem ipsum dolor sit amet consectetur adipisicing elit.
+ type: card
+ id: custom-card
+ - text: |
+ Lorem ipsum dolor sit amet consectetur adipisicing elit.
+ type: card
+ title: Changing the card color
```
- === "Result"
- [![CardCSS]][CardCSS]
-
- [CardCSS]: ../../assets/user_guides/assets/css_change_card.png
+ === "Result"
+ [![CardCSS]][cardcss]
!!! note "Relationship between model ID and CSS ID"
+ Some Vizro components produce a single HTML element with an ID that matches the model ID, allowing you to target it directly using the CSS #id selector. Other components generate multiple HTML elements. Within these, the "core" element will have an ID matching the model ID, while non-core elements may have IDs that are variations of it, such as `{model-id}-title`.
- Some Vizro components produce a single HTML element with an ID that matches the model ID, allowing you to target it
- directly using the CSS #id selector. Other components generate multiple HTML elements. Within these, the "core"
- element will have an ID matching the model ID, while non-core elements may have IDs that are variations of it,
- such as `{model-id}-title`.
-
- In all instances, you can determine the correct selector by using Chrome DevTools or a similar tool after setting the
- appropriate model ID.
-
+ In all instances, you can determine the correct selector by using Chrome DevTools or a similar tool after setting the appropriate model ID.
## Common examples
### Make your CSS responsive to theme switches with variables
-To ensure your CSS adapts to theme changes, we recommend using CSS variables (`var`) whenever possible. For a
-comprehensive list of available variable names, refer to the
-[Bootstrap documentation](https://getbootstrap.com/docs/5.3/customize/css-variables/). Note that our
-Bootstrap stylesheet is still under development, so not all Bootstrap variables are currently available.
-Additionally, you can define your own CSS variables, as demonstrated in the example on
-[changing the container background color](#change-the-styling-of-a-container).
+
+To ensure your CSS adapts to theme changes, we recommend using CSS variables (`var`) whenever possible. For a comprehensive list of available variable names, refer to the [Bootstrap documentation](https://getbootstrap.com/docs/5.3/customize/css-variables/). Note that our Bootstrap stylesheet is still under development, so not all Bootstrap variables are currently available. Additionally, you can define your own CSS variables, as demonstrated in the example on [changing the container background color](#change-the-styling-of-a-container).
### Turn off page title
+
See the example above on [hiding the page title on selected pages](#overwrite-css-for-selected-pages).
### Change the background color of a card
+
See the example above on [customizing CSS properties in selective components](#overwrite-css-for-selected-components).
### Change the global font
+
The default fonts for a Vizro app are `Inter, sans-serif, Arial, serif`.
If you need to change the global font, perhaps to adhere to branding guidelines, follow these steps:
1. Download the desired font from a font provider such as [Google Fonts](https://fonts.google.com/).
-2. Place the font file (`.ttf`, `woff2`, etc.) into your `assets` folder. Here’s an example of what the assets folder might look like:
- 
+1. Place the font file (`.ttf`, `woff2`, etc.) into your `assets` folder. Here’s an example of what the assets folder might look like:
-3. Add the font to your CSS file using the `@font-face` rule and apply the font globally to your Vizro app, making sure
-to specify fallback fonts. Add the following to your `custom.css` file:
+ 
+1. Add the font to your CSS file using the `@font-face` rule and apply the font globally to your Vizro app, making sure to specify fallback fonts. Add the following to your `custom.css` file:
```css
@font-face {
- font-family: PlayfairDisplay;
- src: url("PlayfairDisplay-VariableFont_wght.ttf") format("truetype");
+ font-family: PlayfairDisplay;
+ src: url("PlayfairDisplay-VariableFont_wght.ttf") format("truetype");
}
* {
- font-family: PlayfairDisplay, Inter, sans-serif, Arial, serif;
+ font-family: PlayfairDisplay, Inter, sans-serif, Arial, serif;
}
```
-
-4. Note that the modification above applies solely to the dashboard font. To also change the font within the
-Plotly charts, you must specify this at the beginning of your `app.py` file:
+1. Note that the modification above applies solely to the dashboard font. To also change the font within the Plotly charts, you must specify this at the beginning of your `app.py` file:
```python
import plotly.io as pio
@@ -365,44 +340,42 @@ Plotly charts, you must specify this at the beginning of your `app.py` file:
```
### Reposition the logo
-By default, the logo appears in the top left corner of the dashboard. You can move it further to the left or right by
-adjusting the `padding` of the `#page-header` element. Here is an example of how to achieve this:
+
+By default, the logo appears in the top left corner of the dashboard. You can move it further to the left or right by adjusting the `padding` of the `#page-header` element. Here is an example of how to achieve this:
```css
#page-header {
- padding-left: 8px;
+ padding-left: 8px;
}
```
-
### Change the styling of a container
-If you want to make the subsections of your dashboard stand out more, you can do this by placing your components
-inside a [Container](container.md) and changing the container's styling, for example, background color, borders, padding, etc.
-To do this, you need to change the container's CSS class. Using the DevTool, as explained in the section on
-[identifying the correct CSS selector](#identify-the-correct-css-selector), you'll find that the CSS class for the
-`Container` is `page-component-container`. You can then use this class to set a new `background-color` and `padding`.
+If you want to make the subsections of your dashboard stand out more, you can do this by placing your components inside a [Container](container.md) and changing the container's styling, for example, background color, borders, padding, etc.
+
+To do this, you need to change the container's CSS class. Using the DevTool, as explained in the section on [identifying the correct CSS selector](#identify-the-correct-css-selector), you'll find that the CSS class for the `Container` is `page-component-container`. You can then use this class to set a new `background-color` and `padding`.
!!! example "Style a container"
=== "custom.css"
- ```css
- /* Assign a variable to the dark and light theme */
- [data-bs-theme="dark"] {
- --container-bg-color: #232632;
- }
-
- [data-bs-theme="light"] {
- --container-bg-color: #F5F6F6;
- }
+ ```css
+ /* Assign a variable to the dark and light theme */
+ [data-bs-theme="dark"] {
+ --container-bg-color: #232632;
+ }
+
+ [data-bs-theme="light"] {
+ --container-bg-color: #F5F6F6;
+ }
+
+ /* Use the custom variable var(--container-bg-color) */
+ .page-component-container {
+ background: var(--container-bg-color);
+ padding: 12px;
+ }
+ ```
- /* Use the custom variable var(--container-bg-color) */
- .page-component-container {
- background: var(--container-bg-color);
- padding: 12px;
- }
- ```
=== "app.py"
```py
import vizro.models as vm
@@ -437,12 +410,12 @@ To do this, you need to change the container's CSS class. Using the DevTool, as
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - title: "Page with subsections"
+ - title: Page with subsections
layout:
grid: [[0, 1]]
components:
- type: container
- title: "Container I"
+ title: Container I
components:
- type: graph
figure:
@@ -452,7 +425,7 @@ To do this, you need to change the container's CSS class. Using the DevTool, as
y: sepal_length
color: species
- type: container
- title: "Container II"
+ title: Container II
components:
- type: graph
figure:
@@ -462,13 +435,11 @@ To do this, you need to change the container's CSS class. Using the DevTool, as
y: sepal_length
color: species
```
- === "Result"
- [![StyleContainer]][StyleContainer]
- [StyleContainer]: ../../assets/user_guides/custom_css/style-container.png
+ === "Result"
+ [![StyleContainer]][stylecontainer]
-You will notice that the background colors of the charts are different. To align it with the colors of the container,
-you can make the charts' background transparent.
+You will notice that the background colors of the charts are different. To align it with the colors of the container, you can make the charts' background transparent.
To make the background of all charts transparent:
@@ -492,3 +463,8 @@ def custom_chart(data_frame):
```
+
+[assetscss]: ../../assets/user_guides/assets/css_change.png
+[cardcss]: ../../assets/user_guides/assets/css_change_card.png
+[pagetitle]: ../../assets/user_guides/assets/css_page_title.png
+[stylecontainer]: ../../assets/user_guides/custom_css/style-container.png
diff --git a/vizro-core/docs/pages/user-guides/custom-figures.md b/vizro-core/docs/pages/user-guides/custom-figures.md
index f135127be..3a178932f 100644
--- a/vizro-core/docs/pages/user-guides/custom-figures.md
+++ b/vizro-core/docs/pages/user-guides/custom-figures.md
@@ -1,41 +1,36 @@
# How to create custom figures
-This guide explains how to create custom figures, which is useful when you need a component that reacts to
-[filter](filters.md) and [parameter](parameters.md) controls.
+This guide explains how to create custom figures, which is 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).
## When to use a custom figure
-As described in the flowchart detailing [when to use `Figure`](figure.md), custom figures should be used if
-**both** of the following conditions are met:
+
+As described in the flowchart detailing [when to use `Figure`](figure.md), custom figures should be used if **both** of the following conditions are met:
- You need a figure that doesn't fit into the existing pre-defined components ([`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid]).
- You need a figure that isn't available in our pre-defined figure functions [`vizro.figures`](../API-reference/figure-callables.md).
## Steps to create a custom figure
-1. Define a function that returns a [Dash component](https://dash.plotly.com/#open-source-component-libraries).
-This can, but does not need to, be based on code in our pre-defined figure functions in [`vizro.figures`](../API-reference/figure-callables.md).
-2. Decorate it with `@capture("figure")`.
-3. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
-4. The figure should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments
-will not react to dashboard controls such as [`Filter`](filters.md).
-5. Pass your function to the `figure` argument of the [`Figure`][vizro.models.Figure] model.
+1. Define a function that returns a [Dash component](https://dash.plotly.com/#open-source-component-libraries). This can, but does not need to, be based on code in our pre-defined figure functions in [`vizro.figures`](../API-reference/figure-callables.md).
+1. Decorate it with `@capture("figure")`.
+1. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
+1. The figure should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments will not react to dashboard controls such as [`Filter`](filters.md).
+1. Pass your function to the `figure` argument of the [`Figure`][vizro.models.Figure] model.
The following examples can be used as a base to build more sophisticated figures.
## Examples of custom figures
### Custom KPI card
-To change the design or content of our existing KPI (key performance indicator) cards from
-[`vizro.figures`](../API-reference/figure-callables.md), you can do so by following the steps described above.
-For instance, to make a KPI card with the icon positioned on the right side of the title instead of the left,
-copy and paste the [source code of `kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card) and
-adjust the return statement of the function.
+To change the design or content of our existing KPI (key performance indicator) cards from [`vizro.figures`](../API-reference/figure-callables.md), you can do so by following the steps described above.
+
+For instance, to make a KPI card with the icon positioned on the right side of the title instead of the left, copy and paste the [source code of `kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card) and adjust the return statement of the function.
+
!!! example "Custom KPI card"
=== "app.py"
```{.python pycafe-link}
@@ -107,29 +102,26 @@ adjust the return statement of the function.
```
1. Here we decorate our custom figure function with the `@capture("figure")` decorator.
- 2. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
- 3. We adjust the return statement to include the icon on the right side of the title. This is achieved by swapping the order of the `html.H2` and `html.P` compared to the original `kpi_card`.
- 4. This creates a [`layout`](layouts.md) with four rows and columns. The KPI cards are positioned in the first two cells, while the remaining cells are empty.
- 5. For more information, refer to the API reference for the [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card).
- 6. Our custom figure function `custom_kpi_card` now needs to be passed on to the `vm.Figure`.
+ 1. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
+ 1. We adjust the return statement to include the icon on the right side of the title. This is achieved by swapping the order of the `html.H2` and `html.P` compared to the original `kpi_card`.
+ 1. This creates a [`layout`](layouts.md) with four rows and columns. The KPI cards are positioned in the first two cells, while the remaining cells are empty.
+ 1. For more information, refer to the API reference for the [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card).
+ 1. Our custom figure function `custom_kpi_card` now needs to be passed on to the `vm.Figure`.
=== "app.yaml"
- ```yaml
- # Custom figures are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomKPI]][CustomKPI]
+ Custom figures are currently only possible via Python configuration.
- [CustomKPI]: ../../assets/user_guides/figure/custom_kpi.png
+ === "Result"
+ [![CustomKPI]][customkpi]
### Dynamic HTML header
-You can create a custom figure for any [Dash component](https://dash.plotly.com/#open-source-component-libraries).
-Below is an example of a custom figure that returns a `html.H2` component that dynamically updates based on the selected
-name from a filter.
+
+You can create a custom figure for any [Dash component](https://dash.plotly.com/#open-source-component-libraries). Below is an example of a custom figure that returns a `html.H2` component that dynamically updates based on the selected name from a filter.
+
!!! example "Dynamic HTML header"
=== "app.py"
```{.python pycafe-link}
@@ -159,27 +151,24 @@ name from a filter.
```
1. Here we decorate our custom figure function with the `@capture("figure")` decorator.
- 2. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
- 3. We return a `html.H2` component that dynamically updates based on the selected name from the filter.
- 4. Our custom figure function `dynamic_html_header` now needs to be passed on to the `vm.Figure`.
+ 1. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
+ 1. We return a `html.H2` component that dynamically updates based on the selected name from the filter.
+ 1. Our custom figure function `dynamic_html_header` now needs to be passed on to the `vm.Figure`.
=== "app.yaml"
- ```yaml
- # Custom figures are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomHTML]][CustomHTML]
+ Custom figures are currently only possible via Python configuration.
- [CustomHTML]: ../../assets/user_guides/figure/custom_html.png
+ === "Result"
+ [![CustomHTML]][customhtml]
-
### Dynamic number of cards
-The example below shows how to create multiple cards created from a `pandas.DataFrame` where the
-number of cards displayed dynamically adjusts based on a `vm.Parameter`.
+
+The example below shows how to create multiple cards created from a `pandas.DataFrame` where the number of cards displayed dynamically adjusts based on a `vm.Parameter`.
+
!!! example "Dynamic number of cards"
=== "app.py"
```py
@@ -239,40 +228,39 @@ number of cards displayed dynamically adjusts based on a `vm.Parameter`.
```
1. Here we decorate our custom figure function with the `@capture("figure")` decorator.
- 2. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
- 3. Our decorated figure function `multiple_cards` now needs to be passed on to the `vm.Figure`.
- 4. We add a [`vm.Parameter`](parameters.md) to dynamically adjust the number of cards displayed.
- The parameter targets the `n_rows` argument of the `multiple_cards` function, determining the number of rows
- taken from the data.
+ 1. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
+ 1. Our decorated figure function `multiple_cards` now needs to be passed on to the `vm.Figure`.
+ 1. We add a [`vm.Parameter`](parameters.md) to dynamically adjust the number of cards displayed. The parameter targets the `n_rows` argument of the `multiple_cards` function, determining the number of rows taken from the data.
Run and edit this code in PyCafe
=== "styling.css"
```css
.multiple-cards-container {
- display: flex;
- flex-wrap: wrap;
- gap: 12px;
+ display: flex;
+ flex-wrap: wrap;
+ gap: 12px;
}
.figure-container {
- height: unset;
- width: unset;
+ height: unset;
+ width: unset;
}
.figure-container .card {
- height: 210px;
- width: 240px;
+ height: 210px;
+ width: 240px;
}
```
- === "app.yaml"
- ```yaml
- # Custom figures are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomFigure]][CustomFigure]
- [CustomFigure]: ../../assets/user_guides/figure/custom_multiple_cards.png
+ === "app.yaml"
+ Custom figures are currently only possible via Python configuration.
+ === "Result"
+ [![CustomFigure]][customfigure]
+
+[customfigure]: ../../assets/user_guides/figure/custom_multiple_cards.png
+[customhtml]: ../../assets/user_guides/figure/custom_html.png
+[customkpi]: ../../assets/user_guides/figure/custom_kpi.png
diff --git a/vizro-core/docs/pages/user-guides/custom-tables.md b/vizro-core/docs/pages/user-guides/custom-tables.md
index e990cfbb0..42748820b 100644
--- a/vizro-core/docs/pages/user-guides/custom-tables.md
+++ b/vizro-core/docs/pages/user-guides/custom-tables.md
@@ -1,21 +1,18 @@
# How to create custom Dash AG Grids and Dash DataTables
-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.
+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.
-The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] model accept the `figure` argument, where you can enter
-_any_ [`dash_ag_grid`][vizro.tables.dash_ag_grid] or [`dash_data_table`][vizro.tables.dash_data_table] chart as explained in the [user guide on tables](table.md).
+The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] model accept the `figure` argument, where you can enter _any_ [`dash_ag_grid`][vizro.tables.dash_ag_grid] or [`dash_data_table`][vizro.tables.dash_data_table] chart as explained in the [user guide on tables](table.md).
One reason could be that you want to create a table/grid that requires computations that can be controlled by parameters (see the example below).
### Steps to create a custom table
1. Define a function that returns a `dash_ag_grid.AgGrid` or `dash_table.DataTable` object.
-2. Decorate it with `@capture("ag_grid")` or `@capture("table")`.
-3. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
-4. The table should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments
-will not react to dashboard controls such as [`Filter`](filters.md).
-5. Pass your function to the `figure` argument of the [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid] model.
+1. Decorate it with `@capture("ag_grid")` or `@capture("table")`.
+1. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
+1. The table should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments will not react to dashboard controls such as [`Filter`](filters.md).
+1. Pass your function to the `figure` argument of the [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid] model.
The following examples show a possible version of a custom table. In this case the argument `chosen_columns` was added, which you can control with a parameter:
@@ -70,14 +67,12 @@ The following examples show a possible version of a custom table. In this case t
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
- ```yaml
- # Custom tables are currently only possible via Python configuration
- ```
- === "Result"
- [![Table3]][Table3]
+ Custom tables are currently only possible via Python configuration.
- [Table3]: ../../assets/user_guides/table/custom_table.png
+ === "Result"
+ [![Table3]][table3]
??? example "Custom Dash AgGrid"
=== "app.py"
@@ -136,11 +131,12 @@ The following examples show a possible version of a custom table. In this case t
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
- ```yaml
- # Custom Ag Grids are currently only possible via Python configuration
- ```
+ Custom Ag Grids are currently only possible via Python configuration.
+
=== "Result"
- [![GridCustom]][GridCustom]
+ [![GridCustom]][gridcustom]
- [GridCustom]: ../../assets/user_guides/table/custom_grid.png
+[gridcustom]: ../../assets/user_guides/table/custom_grid.png
+[table3]: ../../assets/user_guides/table/custom_table.png
diff --git a/vizro-core/docs/pages/user-guides/dashboard.md b/vizro-core/docs/pages/user-guides/dashboard.md
index 0b37e03fa..244f65256 100644
--- a/vizro-core/docs/pages/user-guides/dashboard.md
+++ b/vizro-core/docs/pages/user-guides/dashboard.md
@@ -1,16 +1,15 @@
# How to create a dashboard
-This guide shows you how to configure and call a [`Dashboard`][vizro.models.Dashboard] using either
-pydantic models, Python dictionaries, YAML, or JSON.
+
+This guide shows you how to configure and call a [`Dashboard`][vizro.models.Dashboard] using either pydantic models, Python dictionaries, YAML, or JSON.
To create a dashboard:
1. Choose one of the possible configuration syntaxes
-2. Create your `pages`, see our [guide on Pages](pages.md)
-3. (optional) Choose a `theme`, see our [guide on Themes](themes.md)
-4. (optional) Customize your `navigation`, see our [guide on Navigation](navigation.md)
-5. (optional) Set a `title` for your dashboard
-6. Add your `dashboard` to the `build` call of Vizro
-
+1. Create your `pages`, see our [guide on Pages](pages.md)
+1. (optional) Choose a `theme`, see our [guide on Themes](themes.md)
+1. (optional) Customize your `navigation`, see our [guide on Navigation](navigation.md)
+1. (optional) Set a `title` for your dashboard
+1. Add your `dashboard` to the `build` call of Vizro
## Use dashboard configuration options
@@ -37,6 +36,7 @@ To create a dashboard:
Vizro().build(dashboard).run()
```
+
=== "app.py - Python dict"
```py
import vizro.plotly.express as px
@@ -77,6 +77,7 @@ To create a dashboard:
Vizro().build(dashboard).run()
```
+
=== "dashboard.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -101,50 +102,49 @@ To create a dashboard:
type: filter
title: My first dashboard
```
+
=== "dashboard.json"
```json
{
- "pages": [
+ "pages": [
+ {
+ "components": [
+ {
+ "figure": {
+ "_target_": "scatter",
+ "color": "species",
+ "data_frame": "iris",
+ "x": "sepal_length",
+ "y": "petal_width"
+ },
+ "type": "graph"
+ },
{
- "components": [
- {
- "figure": {
- "_target_": "scatter",
- "color": "species",
- "data_frame": "iris",
- "x": "sepal_length",
- "y": "petal_width"
- },
- "type": "graph"
- },
- {
- "figure": {
- "_target_": "histogram",
- "color": "species",
- "data_frame": "iris",
- "x": "sepal_width",
- },
- "type": "graph"
- }
- ],
- "controls": [
- {
- "column": "species",
- "type": "filter"
- }
- ],
- "title": "My first dashboard"
+ "figure": {
+ "_target_": "histogram",
+ "color": "species",
+ "data_frame": "iris",
+ "x": "sepal_width"
+ },
+ "type": "graph"
}
- ]
+ ],
+ "controls": [
+ {
+ "column": "species",
+ "type": "filter"
+ }
+ ],
+ "title": "My first dashboard"
+ }
+ ]
}
```
- === "Result"
- [![Dashboard]][Dashboard]
- [Dashboard]: ../../assets/user_guides/dashboard/dashboard.png
+ === "Result"
+ [![Dashboard]][dashboard]
!!! note "Extra `.py` files for `yaml` and `json` required"
-
Note that in the `yaml` and `json` example an extra `.py` is required to register the data and parse the yaml/json configuration.
=== "app.py for yaml"
@@ -164,6 +164,7 @@ To create a dashboard:
Vizro().build(dashboard).run()
```
+
=== "app.py for json"
```py
import json
@@ -187,7 +188,6 @@ After running the dashboard, you can access the dashboard via `localhost:8050`.
If supplied, the `title` of the [`Dashboard`][vizro.models.Dashboard] displays a heading at the top of every page.
-
## Add a dashboard logo
Vizro will [automatically incorporate the dashboard logo](assets.md/#add-a-logo-image) in the top-left corner of each page if an image named `logo.` is present within the assets folder.
@@ -196,11 +196,10 @@ Vizro will [automatically incorporate the dashboard logo](assets.md/#add-a-logo-
## Browser title
-The [website icon](assets.md/#change-the-favicon), Dashboard `title` (if supplied) and [Page `title`][vizro.models.Page] are displayed in the browser's
-title bar. For example, if your Dashboard `title` is "Vizro Demo" and the Page `title` is "Homepage", then the title in the browser tab will be "Vizro Demo: Homepage".
+The [website icon](assets.md/#change-the-favicon), Dashboard `title` (if supplied) and [Page `title`][vizro.models.Page] are displayed in the browser's title bar. For example, if your Dashboard `title` is "Vizro Demo" and the Page `title` is "Homepage", then the title in the browser tab will be "Vizro Demo: Homepage".
## Meta tags for social media
-Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat
-clients. The preview includes the `URL`, `title`, plus an [image](assets.md/#include-a-meta-tags-image) and
-[Page `description`][vizro.models.Page] (if supplied). To see an example, try sharing an example from the [Vizro examples gallery](https://vizro.mckinsey.com/).
+Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat clients. The preview includes the `URL`, `title`, plus an [image](assets.md/#include-a-meta-tags-image) and [Page `description`][vizro.models.Page] (if supplied). To see an example, try sharing an example from the [Vizro examples gallery](https://vizro.mckinsey.com/).
+
+[dashboard]: ../../assets/user_guides/dashboard/dashboard.png
diff --git a/vizro-core/docs/pages/user-guides/data.md b/vizro-core/docs/pages/user-guides/data.md
index 51bf84b97..d19b8aafb 100644
--- a/vizro-core/docs/pages/user-guides/data.md
+++ b/vizro-core/docs/pages/user-guides/data.md
@@ -2,11 +2,12 @@
Vizro supports two different types of data:
-* [Static data](#static-data): pandas DataFrame. This is the simplest method and best to use if you do not need the more advanced functionality of dynamic data.
-* [Dynamic data](#dynamic-data): function that returns a pandas DataFrame. This is a bit more complex to understand but has more advanced functionality such as the ability to refresh data while the dashboard is running.
+- [Static data](#static-data): pandas DataFrame. This is the simplest method and best to use if you do not need the more advanced functionality of dynamic data.
+- [Dynamic data](#dynamic-data): function that returns a pandas DataFrame. This is a bit more complex to understand but has more advanced functionality such as the ability to refresh data while the dashboard is running.
The following flowchart shows what you need to consider when choosing how to set up your data.
-``` mermaid
+
+```mermaid
graph TD
refresh["`Do you need your data to refresh while the dashboard is running?`"]
specification["`Do you need to specify your dashboard through a configuration language like YAML?`"]
@@ -27,11 +28,10 @@ graph TD
```
??? note "Static vs. dynamic data comparison"
-
This table gives a full comparison between static and dynamic data. Do not worry if you do not yet understand everything in it; it will become clearer after reading more about [static data](#static-data) and [dynamic data](#dynamic-data)!
| | Static | Dynamic |
- |---------------------------------------------------------------|------------------|------------------------------------------|
+ | ------------------------------------------------------------- | ---------------- | ---------------------------------------- |
| Required Python type | pandas DataFrame | Function that returns a pandas DataFrame |
| Can be supplied directly in `data_frame` argument of `figure` | Yes | No |
| Can be referenced by name after adding to data manager | Yes | Yes |
@@ -73,14 +73,13 @@ The below example uses the Iris data saved to a file `iris.csv` in the same dire
```
1. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
- === "Result"
- [![DataBasic]][DataBasic]
- [DataBasic]: ../../assets/user_guides/data/data_pandas_dataframe.png
+ === "Result"
+ [![DataBasic]][databasic]
The [`Graph`][vizro.models.Graph], [`AgGrid`][vizro.models.AgGrid] and [`Table`][vizro.models.Table] models all have an argument called `figure`. This accepts a function (in the above example, `px.scatter`) that takes a pandas DataFrame as its first argument. The name of this argument is always `data_frame`. When configuring the dashboard using Python, it is optional to give the name of the argument: if you like, you could write `data_frame=iris` instead of `iris`.
-!!! note
+!!! note
With static data, once the dashboard is running, the data shown in the dashboard cannot change even if the source data in `iris.csv` changes. The code `iris = pd.read_csv("iris.csv")` is only executed once when the dashboard is first started. If you would like changes to source data to flow through to the dashboard then you must use [dynamic data](#dynamic-data).
### Reference by name
@@ -107,27 +106,27 @@ If you would like to specify your dashboard configuration through YAML then you
```
1. `"iris"` is the name of a data source added to the data manager. This data is a pandas DataFrame created by reading from the CSV file `iris.csv`.
+
=== "dashboard.yaml"
```yaml
pages:
- - components:
- - figure:
+ - components:
+ figure:
_target_: box
data_frame: iris # (1)!
x: species
y: petal_width
color: species
type: graph
- title: Static data example
+ title: Static data example
```
1. Refer to the `"iris"` data source in the data manager.
- === "Result"
- [![DataBasic]][DataBasic]
- [DataBasic]: ../../assets/user_guides/data/data_pandas_dataframe.png
+ === "Result"
+ [![DataBasic]][databasic]
-It is also possible to refer to a named data source using the Python API: `px.scatter("iris", ...)` or `px.scatter(data_frame="iris", ...)` would work if the `"iris"` data source has been registered in the data manager.
+It is also possible to refer to a named data source using the Python API: `px.scatter("iris", ...)` or `px.scatter(data_frame="iris", ...)` would work if the `"iris"` data source has been registered in the data manager.
## Dynamic data
@@ -166,14 +165,12 @@ The example below shows how data is fetched dynamically every time the page is r
```
1. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
- 2. To demonstrate that dynamic data can change when the page is refreshed, select 50 points at random. This simulates what would happen if your file `iris.csv` were constantly changing.
- 3. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()`; doing so would result in static data that cannot be reloaded.
- 4. Dynamic data is referenced by the name of the data source `"iris"`.
+ 1. To demonstrate that dynamic data can change when the page is refreshed, select 50 points at random. This simulates what would happen if your file `iris.csv` were constantly changing.
+ 1. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()`; doing so would result in static data that cannot be reloaded.
+ 1. Dynamic data is referenced by the name of the data source `"iris"`.
=== "Result"
- [![DynamicData]][DynamicData]
-
- [DynamicData]: ../../assets/user_guides/data/dynamic_data.gif
+ [![DynamicData]][dynamicdata]
Since dynamic data sources must always be added to the data manager and referenced by name, they may be used in YAML configuration [exactly the same way as for static data sources](#reference-by-name).
@@ -184,10 +181,10 @@ By default, a dynamic data function executes every time the dashboard is refresh
The Vizro data manager has a server-side caching mechanism to help solve this. Vizro's cache uses [Flask-Caching](https://flask-caching.readthedocs.io/en/latest/), which supports a number of possible cache backends and [configuration options](https://flask-caching.readthedocs.io/en/latest/#configuring-flask-caching). By default, the cache is turned off.
+
In a development environment the easiest way to enable caching is to use a [simple memory cache](https://cachelib.readthedocs.io/en/stable/simple/) with the default configuration options. This is achieved by adding one line to the above example to set `data_manager.cache`:
!!! example "Simple cache with default timeout of 5 minutes"
-
```py hl_lines="13"
from flask_caching import Cache
from vizro import Vizro
@@ -225,7 +222,6 @@ data_manager.cache = Cache(config={"CACHE_TYPE": "SimpleCache", "CACHE_DEFAULT_T
```
!!! warning
-
Simple cache exists purely for single-process development purposes and is not intended to be used in production. If you deploy with multiple workers, [for example with Gunicorn](run.md/#gunicorn), then you should use a production-ready cache backend. All of Flask-Caching's [built-in backends](https://flask-caching.readthedocs.io/en/latest/#built-in-cache-backends) other than `SimpleCache` are suitable for production. In particular, you might like to use [`FileSystemCache`](https://cachelib.readthedocs.io/en/stable/file/) or [`RedisCache`](https://cachelib.readthedocs.io/en/stable/redis/):
```py title="Production-ready caches"
@@ -239,7 +235,9 @@ data_manager.cache = Cache(config={"CACHE_TYPE": "SimpleCache", "CACHE_DEFAULT_T
Since Flask-Caching relies on [`pickle`](https://docs.python.org/3/library/pickle.html), which can execute arbitrary code during unpickling, you should not cache data from untrusted sources. Doing so [could be unsafe](https://github.com/pallets-eco/flask-caching/pull/209).
Note that when a production-ready cache backend is used, the cache is persisted beyond the Vizro process and is not cleared by restarting your server. To clear the cache then you must do so manually, for example, if you use `FileSystemCache` then you would delete your `cache` directory. Persisting the cache can also be useful for development purposes when handling data that takes a long time to load: even if you do not need the data to refresh while your dashboard is running, it can speed up your development loop to use dynamic data with a cache that is persisted between repeated runs of Vizro.
+
+
#### Set timeouts
You can change the timeout of the cache independently for each dynamic data source in the data manager using the `timeout` setting (measured in seconds). A `timeout` of 0 indicates that the cache does not expire. This is effectively the same as using [static data](#static-data).
@@ -278,8 +276,8 @@ In general, a parametrized dynamic data source should always return a pandas Dat
To add a parameter to control a dynamic data source, do the following:
1. add the appropriate argument to your dynamic data function and specify a default value for the argument.
-2. give an `id` to all components that have the data source you wish to alter through a parameter.
-3. [add a parameter](parameters.md) with `targets` of the form `.data_frame.` and a suitable [selector](selectors.md).
+1. give an `id` to all components that have the data source you wish to alter through a parameter.
+1. [add a parameter](parameters.md) with `targets` of the form `.data_frame.` and a suitable [selector](selectors.md).
For example, let us extend the [dynamic data example](#dynamic-data) above into an example of how parametrized dynamic data works. The `load_iris_data` can take an argument `number_of_points` controlled from the dashboard with a [`Slider`][vizro.models.Slider].
@@ -318,21 +316,18 @@ For example, let us extend the [dynamic data example](#dynamic-data) above into
```
1. `load_iris_data` takes a single argument, `number_of_points`, with a default value of 10.
- 2. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
- 3. Sample points at random, where `number_of_points` gives the number of points selected.
- 4. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()` or `load_iris_data(number_of_points=...)`; doing so would result in static data that cannot be reloaded.
- 5. Give the `vm.Graph` component `id="graph"` so that the `vm.Parameter` can target it. Dynamic data is referenced by the name of the data source `"iris"`.
- 6. Create a `vm.Parameter` to target the `number_of_points` argument for the `data_frame` used in `graph`.
+ 1. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
+ 1. Sample points at random, where `number_of_points` gives the number of points selected.
+ 1. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()` or `load_iris_data(number_of_points=...)`; doing so would result in static data that cannot be reloaded.
+ 1. Give the `vm.Graph` component `id="graph"` so that the `vm.Parameter` can target it. Dynamic data is referenced by the name of the data source `"iris"`.
+ 1. Create a `vm.Parameter` to target the `number_of_points` argument for the `data_frame` used in `graph`.
=== "Result"
- [![ParametrizedDynamicData]][ParametrizedDynamicData]
-
- [ParametrizedDynamicData]: ../../assets/user_guides/data/parametrized_dynamic_data.gif
+ [![ParametrizedDynamicData]][parametrizeddynamicdata]
Parametrized data loading is compatible with [caching](#configure-cache). The cache uses [memoization](https://flask-caching.readthedocs.io/en/latest/#memoization), so that the dynamic data function's arguments are included in the cache key. This means that `load_iris_data(number_of_points=10)` is cached independently of `load_iris_data(number_of_points=20)`.
!!! warning
-
You should always [treat the content of user input as untrusted](https://community.plotly.com/t/writing-secure-dash-apps-community-thread/54619). For example, you should not expose a filepath to load without passing it through a function like [`werkzeug.utils.secure_filename`](https://werkzeug.palletsprojects.com/en/3.0.x/utils/#werkzeug.utils.secure_filename), or you might enable arbitrary access to files on your server.
You cannot pass [nested parameters](parameters.md#nested-parameters) to dynamic data. You can only target the top-level arguments of the data loading function, not the nested keys in a dictionary.
@@ -354,7 +349,6 @@ When the page is refreshed, the behavior of a dynamic filter is as follows:
For example, let us add two filters to the [dynamic data example](#dynamic-data) above:
!!! example "Dynamic filters"
-
```py hl_lines="10 20 21"
from vizro import Vizro
import pandas as pd
@@ -386,8 +380,8 @@ For example, let us add two filters to the [dynamic data example](#dynamic-data)
```
1. We sample only 5 rather than 50 points so that changes to the available values in the filtered columns are more apparent when the page is refreshed.
- 2. This filter implicitly controls the dynamic data source `"iris"`, which supplies the `data_frame` to the targeted `vm.Graph`. On page refresh, Vizro reloads this data, finds all the unique values in the `"species"` column and sets the categorical selector's `options` accordingly.
- 3. Similarly, on page refresh, Vizro finds the minimum and maximum values of the `"sepal_length"` column in the reloaded data and sets new `min` and `max` values for the numerical selector accordingly.
+ 1. This filter implicitly controls the dynamic data source `"iris"`, which supplies the `data_frame` to the targeted `vm.Graph`. On page refresh, Vizro reloads this data, finds all the unique values in the `"species"` column and sets the categorical selector's `options` accordingly.
+ 1. Similarly, on page refresh, Vizro finds the minimum and maximum values of the `"sepal_length"` column in the reloaded data and sets new `min` and `max` values for the numerical selector accordingly.
Consider a filter that depends on dynamic data, where you do **not** want the available values to change when the dynamic data changes. You should manually specify the `selector`'s `options` field (categorical selector) or `min` and `max` fields (numerical selector). In the above example, this could be achieved as follows:
@@ -409,10 +403,13 @@ controls = [
When Vizro initially builds a filter that depends on parametrized dynamic data loading, data is loaded using the default argument values. This data is used to:
-* perform initial validation
-* check which data sources contain the specified `column` (unless `targets` is explicitly specified) and
-* find the type of selector to use (unless `selector` is explicitly specified).
+- perform initial validation
+- check which data sources contain the specified `column` (unless `targets` is explicitly specified) and
+- find the type of selector to use (unless `selector` is explicitly specified).
!!! note
-
When the value of a dynamic data parameter is changed by a dashboard user, the data underlying a dynamic filter can change. Currently this change affects page components such as `vm.Graph` but does not affect the available values shown in a dynamic filter, which only update on page refresh. This functionality will be coming soon!
+
+[databasic]: ../../assets/user_guides/data/data_pandas_dataframe.png
+[dynamicdata]: ../../assets/user_guides/data/dynamic_data.gif
+[parametrizeddynamicdata]: ../../assets/user_guides/data/parametrized_dynamic_data.gif
diff --git a/vizro-core/docs/pages/user-guides/extensions.md b/vizro-core/docs/pages/user-guides/extensions.md
index 2c7efc9ac..74a740448 100644
--- a/vizro-core/docs/pages/user-guides/extensions.md
+++ b/vizro-core/docs/pages/user-guides/extensions.md
@@ -2,64 +2,49 @@
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).
+- **[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.
+- **[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.
-* **[CSS customizations](#css-customizations)**. You can add custom CSS to any Vizro dashboard, enabling users to deviate from the default styling and create a unique look and feel for their dashboard.
-
-* **[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
+- **[CSS customizations](#css-customizations)**. You can add custom CSS to any Vizro dashboard, enabling users to deviate from the default styling and create a unique look and feel for their dashboard.
+- **[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
-
+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)).
+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.
-
+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).
+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
+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:
+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
@@ -93,14 +78,12 @@ enabling an interaction between data points in a scatter plot and the content of
## CSS customizations
-Vizro is opinionated about visual formatting, and some elements, such as the layout of the navigation and controls,
-are fixed. You can customize some settings such as background colors, fonts, and other styles via CSS overrides.
+Vizro is opinionated about visual formatting, and some elements, such as the layout of the navigation and controls, are fixed. You can customize some settings such as background colors, fonts, and other styles via CSS overrides.
For more information, see our documentation on [customizing CSS](custom-css.md)
## 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
+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)
diff --git a/vizro-core/docs/pages/user-guides/figure.md b/vizro-core/docs/pages/user-guides/figure.md
index 0589fad3b..03bfa412a 100644
--- a/vizro-core/docs/pages/user-guides/figure.md
+++ b/vizro-core/docs/pages/user-guides/figure.md
@@ -1,26 +1,19 @@
# How to use figures
-This guide shows you how to add any [Dash component](https://dash.plotly.com/#open-source-component-libraries) that needs to be reactive to [filter](filters.md) and [parameter](parameters.md) controls.
-If you want to add a static Dash component to your page, use [custom components](custom-components.md) instead.
+This guide shows you how to add any [Dash component](https://dash.plotly.com/#open-source-component-libraries) that needs to be reactive to [filter](filters.md) and [parameter](parameters.md) controls. If you want to add a static Dash component to your page, use [custom components](custom-components.md) instead.
-[`Figure`][vizro.models.Figure] provides a flexible foundation for all types of reactive Dash components in Vizro.
-The [`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] and [`AgGrid`][vizro.models.AgGrid] components are
-specific implementations of `Figure`. They serve as intuitive shortcuts, embedding behaviors and interactions specific
-to their purposes.
+[`Figure`][vizro.models.Figure] provides a flexible foundation for all types of reactive Dash components in Vizro. The [`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] and [`AgGrid`][vizro.models.AgGrid] components are specific implementations of `Figure`. They serve as intuitive shortcuts, embedding behaviors and interactions specific to their purposes.
-If these more specific models already achieve what you need then they should be used in preference to
-the more generic `Figure`. Remember that it is possible to supply [custom charts](custom-charts.md) to `Graph`
-and [custom tables](custom-tables.md) to `Table`.
+If these more specific models already achieve what you need then they should be used in preference to the more generic `Figure`. Remember that it is possible to supply [custom charts](custom-charts.md) to `Graph` and [custom tables](custom-tables.md) to `Table`.
-There are already a few figure functions you can reuse, see the section on [KPI cards](#key-performance-indicator-kpi-cards)
-for more details:
+There are already a few figure functions you can reuse, see the section on [KPI cards](#key-performance-indicator-kpi-cards) for more details:
- [`kpi_card`][vizro.figures.kpi_card]
- [`kpi_card_reference`][vizro.figures.kpi_card_reference]
The following flowchart shows what you need to consider when choosing which model to use:
-``` mermaid
+```mermaid
graph TD
first["`Does your desired component exist in Vizro, e.g. Graph, Table or AgGrid?`"]
specific-component([Use the specific component])
@@ -40,14 +33,12 @@ graph TD
classDef clickable color:#4051b5;
```
-
To add a `Figure` to your page:
1. Add the `Figure` model to the components argument of the [Page][vizro.models.Page] model.
-2. Use an existing figure function from [`vizro.figures`](../API-reference/figure-callables.md) and pass it to the `figure` argument of the `Figure` model.
+1. Use an existing figure function from [`vizro.figures`](../API-reference/figure-callables.md) and pass it to the `figure` argument of the `Figure` model.
!!! example "Use existing figure functions"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -99,40 +90,25 @@ To add a `Figure` to your page:
selector:
type: radio_items
layout:
- grid:
- [
- [0, -1, -1, -1],
- [-1, -1, -1, -1],
- [-1, -1, -1, -1],
- [-1, -1, -1, -1],
- [-1, -1, -1, -1],
- ]
+ grid: [[0, -1, -1, -1], [-1, -1, -1, -1], [-1, -1, -1, -1], [-1, -1, -1, -1],
+ [-1, -1, -1, -1]]
title: KPI card
```
- === "Result"
- [![Figure]][Figure]
-
- [Figure]: ../../assets/user_guides/figure/figure.png
+ === "Result"
+ [![Figure]][figure]
### Key Performance Indicator (KPI) cards
-A KPI card is a dynamic card that can display a single value, but optionally, can also include a title, icon, and reference value.
-It is a common visual component to display key metrics in a dashboard. Vizro supports two pre-defined KPI card functions:
-- [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card): A KPI card that shows a single value found
-by performing an aggregation function (by default, `sum`) over a specified column.
-Required arguments are `data_frame` and `value_column`.
+A KPI card is a dynamic card that can display a single value, but optionally, can also include a title, icon, and reference value. It is a common visual component to display key metrics in a dashboard. Vizro supports two pre-defined KPI card functions:
-- [`kpi_card_with_reference`](../API-reference/figure-callables.md#vizro.figures.kpi_card_reference): A KPI card that shows a single value
-and a delta comparison to a reference value found by performing an aggregation function (by default, `sum`) over the specified columns.
-Required arguments are `data_frame`, `value_column` and `reference_column`.
+- [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card): A KPI card that shows a single value found by performing an aggregation function (by default, `sum`) over a specified column. Required arguments are `data_frame` and `value_column`.
-As described in the [API reference](../API-reference/figure-callables.md) and illustrated in the below example, these
-functions have several arguments to customize your KPI cards. If you require a level of customization that is not
-possible with the built-in functions then you can create a [custom figure](custom-figures.md).
+- [`kpi_card_with_reference`](../API-reference/figure-callables.md#vizro.figures.kpi_card_reference): A KPI card that shows a single value and a delta comparison to a reference value found by performing an aggregation function (by default, `sum`) over the specified columns. Required arguments are `data_frame`, `value_column` and `reference_column`.
-!!! example "KPI card variations"
+As described in the [API reference](../API-reference/figure-callables.md) and illustrated in the below example, these functions have several arguments to customize your KPI cards. If you require a level of customization that cannot be done with the built-in functions then you can create a [custom figure](custom-figures.md).
+!!! example "KPI card variations"
=== "app.py"
```{.python pycafe-link}
import pandas as pd
@@ -258,8 +234,8 @@ possible with the built-in functions then you can create a [custom figure](custo
value_column: Actual
reference_column: Reference
title: KPI reference with formatting
- value_format: "{value:.2f}€"
- reference_format: "{delta:+.2f}€ vs. last year ({reference:.2f}€)"
+ value_format: '{value:.2f}€'
+ reference_format: '{delta:+.2f}€ vs. last year ({reference:.2f}€)'
type: figure
- figure:
_target_: kpi_card_reference
@@ -276,7 +252,9 @@ possible with the built-in functions then you can create a [custom figure](custo
grid: [[0, 1, 2, 3], [4, 5, 6, 7], [-1, -1, -1, -1], [-1, -1, -1, -1]]
title: KPI cards
```
+
=== "Result"
- [![KPICards]][KPICards]
+ [![KPICards]][kpicards]
- [KPICards]: ../../assets/user_guides/figure/kpi_cards.png
+[figure]: ../../assets/user_guides/figure/figure.png
+[kpicards]: ../../assets/user_guides/figure/kpi_cards.png
diff --git a/vizro-core/docs/pages/user-guides/filters.md b/vizro-core/docs/pages/user-guides/filters.md
index bc3649178..8228ecbe7 100644
--- a/vizro-core/docs/pages/user-guides/filters.md
+++ b/vizro-core/docs/pages/user-guides/filters.md
@@ -2,8 +2,7 @@
This guide shows you how to add filters to your dashboard. One main way to interact with the charts/components on your page is by filtering the underlying data. A filter selects a subset of rows of a component's underlying DataFrame which alters the appearance of that component on the page.
-The [`Page`][vizro.models.Page] model accepts the `controls` argument, where you can enter a [`Filter`][vizro.models.Filter] model.
-This model enables the automatic creation of [selectors](selectors.md) (for example, `Dropdown` or `RangeSlider`) that operate on the charts/components on the screen.
+The [`Page`][vizro.models.Page] model accepts the `controls` argument, where you can enter a [`Filter`][vizro.models.Filter] model. This model enables the automatic creation of [selectors](selectors.md) (for example, `Dropdown` or `RangeSlider`) that operate on the charts/components on the screen.
By default, filters that control components with [dynamic data](data.md#dynamic-data) are [dynamically updated](data.md#filters) when the underlying data changes while the dashboard is running.
@@ -12,7 +11,7 @@ By default, filters that control components with [dynamic data](data.md#dynamic-
To add a filter to your page, do the following:
1. add the [`Filter`][vizro.models.Filter] model into the `controls` argument of the [`Page`][vizro.models.Page] model
-2. configure the `column` argument, which denotes the target column to be filtered
+1. configure the `column` argument, which denotes the target column to be filtered
You can also set `targets` to specify which components on the page the filter should apply to. If this is not explicitly set then `targets` defaults to all components on the page whose data source includes `column`.
@@ -39,6 +38,7 @@ You can also set `targets` to specify which components on the page the filter sh
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -57,17 +57,15 @@ You can also set `targets` to specify which components on the page the filter sh
type: filter
title: My first page
```
- === "Result"
- [![Filter]][Filter]
-
- [Filter]: ../../assets/user_guides/control/control1.png
+ === "Result"
+ [![Filter]][filter]
The selector is configured automatically based on the target column type data as follows:
- - Categorical data uses [`vm.Dropdown(multi=True)`][vizro.models.Dropdown] where `options` is the set of unique values found in `column` across all the data sources of components in `targets`.
- - [Numerical data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_numeric_dtype.html) uses [`vm.RangeSlider`][vizro.models.RangeSlider] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`.
- - [Temporal data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_datetime64_any_dtype.html) uses [`vm.DatePicker(range=True)`][vizro.models.DatePicker] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`. A column can be converted to this type with [pandas.to_datetime](https://pandas.pydata.org/docs/reference/api/pandas.to_datetime.html).
+- Categorical data uses [`vm.Dropdown(multi=True)`][vizro.models.Dropdown] where `options` is the set of unique values found in `column` across all the data sources of components in `targets`.
+- [Numerical data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_numeric_dtype.html) uses [`vm.RangeSlider`][vizro.models.RangeSlider] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`.
+- [Temporal data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_datetime64_any_dtype.html) uses [`vm.DatePicker(range=True)`][vizro.models.DatePicker] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`. A column can be converted to this type with [pandas.to_datetime](https://pandas.pydata.org/docs/reference/api/pandas.to_datetime.html).
The following example demonstrates these default selector types.
@@ -107,6 +105,7 @@ The following example demonstrates these default selector types.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -129,15 +128,13 @@ The following example demonstrates these default selector types.
type: filter
title: My first page
```
- === "Result"
- [![Filter]][Filter]
- [Filter]: ../../assets/user_guides/selectors/default_filter_selectors.png
+ === "Result"
+ [![Filter]][filter]
## Change selector
-If you want to have a different selector for your filter, you can give the `selector` argument of the [`Filter`][vizro.models.Filter] a different selector model.
-Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropdown`][vizro.models.Dropdown], [`RadioItems`][vizro.models.RadioItems], [`RangeSlider`][vizro.models.RangeSlider], [`Slider`][vizro.models.Slider], and [`DatePicker`][vizro.models.DatePicker].
+If you want to have a different selector for your filter, you can give the `selector` argument of the [`Filter`][vizro.models.Filter] a different selector model. Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropdown`][vizro.models.Dropdown], [`RadioItems`][vizro.models.RadioItems], [`RangeSlider`][vizro.models.RangeSlider], [`Slider`][vizro.models.Slider], and [`DatePicker`][vizro.models.DatePicker].
!!! example "Filter with different selector"
=== "app.py"
@@ -162,6 +159,7 @@ Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropd
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -181,11 +179,9 @@ Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropd
type: filter
title: My first page
```
- === "Result"
-
- [![Selector]][Selector]
- [Selector]: ../../assets/user_guides/control/control2.png
+ === "Result"
+ [![Selector]][selector]
## Further customization
@@ -220,6 +216,7 @@ Below is an advanced example where we only target one page component, and where
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -244,17 +241,19 @@ Below is an advanced example where we only target one page component, and where
controls:
- column: petal_length
targets:
- - scatter_chart
+ - scatter_chart
selector:
step: 1
type: range_slider
type: filter
title: My first page
```
- === "Result"
-
- [![Advanced]][Advanced]
- [Advanced]: ../../assets/user_guides/control/control3.png
+ === "Result"
+ [![Advanced]][advanced]
To further customize selectors, see our [how-to-guide on creating custom components](custom-components.md).
+
+[advanced]: ../../assets/user_guides/control/control3.png
+[filter]: ../../assets/user_guides/control/control1.png
+[selector]: ../../assets/user_guides/control/control2.png
diff --git a/vizro-core/docs/pages/user-guides/graph.md b/vizro-core/docs/pages/user-guides/graph.md
index 36c670997..1c3ffc8bc 100755
--- a/vizro-core/docs/pages/user-guides/graph.md
+++ b/vizro-core/docs/pages/user-guides/graph.md
@@ -6,25 +6,18 @@ The [`Graph`][vizro.models.Graph] model is the most used component in many dashb
To add a [`Graph`][vizro.models.Graph] to your page, do the following:
-1. insert the [`Graph`][vizro.models.Graph] model into the `components` argument of the
-[`Page`][vizro.models.Page] model
-2. enter any of the currently available charts of the open source library [`plotly.express`](https://plotly.com/python/plotly-express/) into the `figure` argument
+1. insert the [`Graph`][vizro.models.Graph] model into the `components` argument of the [`Page`][vizro.models.Page] model
+1. enter any of the currently available charts of the open source library [`plotly.express`](https://plotly.com/python/plotly-express/) into the `figure` argument
!!! note
+ To use the [`plotly.express`](https://plotly.com/python/plotly-express/) chart in a Vizro dashboard, you need to import it as `import vizro.plotly.express as px`. This leaves any of the [`plotly.express`](https://plotly.com/python/plotly-express/) functionality untouched yet enables _direct insertion_ into the [`Graph`][vizro.models.Graph] model _as is_.
- In order to use the [`plotly.express`](https://plotly.com/python/plotly-express/) chart in a Vizro dashboard, you need to import it as `import vizro.plotly.express as px`.
- This leaves any of the [`plotly.express`](https://plotly.com/python/plotly-express/) functionality untouched, but allows _direct insertion_ into the [`Graph`][vizro.models.Graph] model _as is_.
-
- Note also that the `plotly.express` chart needs to have a `data_frame` argument. In case you require a chart without
- a `data_frame` argument (for example, the [`imshow` chart](https://plotly.com/python/imshow/)), refer to our
- [guide on custom charts](custom-charts.md).
-
+ Note also that the `plotly.express` chart needs to have a `data_frame` argument. In case you require a chart without a `data_frame` argument (for example, the [`imshow` chart](https://plotly.com/python/imshow/)), refer to our [guide on custom charts](custom-charts.md).
## Insert Plotly chart
!!! example "Graph"
=== "app.py"
-
```{.python pycafe-link}
import vizro.models as vm
import vizro.plotly.express as px
@@ -47,25 +40,24 @@ To add a [`Graph`][vizro.models.Graph] to your page, do the following:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: scatter_matrix
- color: species
- data_frame: iris
- dimensions: ["sepal_length", "sepal_width", "petal_length", "petal_width"]
- type: graph
- title: My first page
+ - components:
+ - figure:
+ _target_: scatter_matrix
+ color: species
+ data_frame: iris
+ dimensions: [sepal_length, sepal_width, petal_length, petal_width]
+ type: graph
+ title: My first page
```
- === "Result"
- [![Graph]][Graph]
-
- [Graph]: ../../assets/user_guides/components/graph.png
+ === "Result"
+ [![Graph]][graph]
In the Python example we directly inserted the pandas DataFrame `df` into `figure=px.scatter_matrix(df, ...)`. This is [one way to supply data to a chart](data.md#supply-directly). For the YAML version, we [refer to the data source by name](data.md#reference-by-name) as `data_frame: iris`. For a full explanation of the different methods you can use to send data to your dashboard, see [our guide to using data in Vizro](data.md).
@@ -73,31 +65,24 @@ In the Python example we directly inserted the pandas DataFrame `df` into `figur
You will need to create a custom chart if you want to customize the Plotly chart beyond a function call, for example by:
-* using post-update methods like `update_layout`, `update_xaxes`, `update_traces`, or
-* by creating a custom `plotly.graph_objects.Figure()` object and manually adding traces with `add_trace`.
-
-For more details, refer to our [user guide on custom chart](custom-charts.md) and the
-[Plotly documentation on updating figures](https://plotly.com/python/creating-and-updating-figures/).
+- using post-update methods like `update_layout`, `update_xaxes`, `update_traces`, or
+- by creating a custom `plotly.graph_objects.Figure()` object and manually adding traces with `add_trace`.
+For more details, refer to our [user guide on custom chart](custom-charts.md) and the [Plotly documentation on updating figures](https://plotly.com/python/creating-and-updating-figures/).
## Add title, header, and footer
-The [`Graph`][vizro.models.Graph] accepts a `title`, `header` and `footer` argument. This is useful for providing
-context to the data being displayed, or for adding a description of the data.
+The [`Graph`][vizro.models.Graph] accepts a `title`, `header` and `footer` argument. This is useful for context on the data being displayed, or for adding a description of the data.
- **title**: Displayed as an [H3 header](https://dash.plotly.com/dash-html-components/h3), useful for summarizing the main topic or insight of the component.
- **header**: Accepts markdown text, ideal for extra descriptions, subtitles, or detailed data insights.
- **footer**: Accepts markdown text, commonly used for citing data sources, providing information on the last update, or adding disclaimers.
-
!!! note
-
- Although you can directly provide a `title` to the Plotly Express chart, we recommend using `Graph.title` for
- proper alignment with other components on the screen.
+ Although you can directly give a `title` to the Plotly Express chart, we recommend using `Graph.title` for proper alignment with other components on the screen.
!!! example "Formatted Graph"
=== "app.py"
-
```{.python pycafe-link}
import vizro.models as vm
@@ -126,31 +111,34 @@ context to the data being displayed, or for adding a description of the data.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: scatter
- x: sepal_width
- y: sepal_length
- color: species
- data_frame: iris
- title: Relationships between Sepal Width and Sepal Length
- header: |
- Each point in the scatter plot represents one of the 150 iris flowers, with colors indicating their
- types. The Setosa type is easily identifiable by its short and wide sepals.
-
- However, there is still overlap between the Versicolor and Virginica types when considering only sepal
- width and length.
- footer: |
- SOURCE: **Plotly iris data set, 2024**
- type: graph
- title: Formatted Graph
+ - components:
+ - figure:
+ _target_: scatter
+ x: sepal_width
+ y: sepal_length
+ color: species
+ data_frame: iris
+ title: Relationships between Sepal Width and Sepal Length
+ header: |
+ Each point in the scatter plot represents one of the 150 iris flowers, with colors indicating their
+ types. The Setosa type is easily identifiable by its short and wide sepals.
+
+ However, there is still overlap between the Versicolor and Virginica types when considering only sepal
+ width and length.
+ footer: |
+ SOURCE: **Plotly iris data set, 2024**
+ type: graph
+ title: Formatted Graph
```
+
=== "Result"
- [![FormattedGraph]][FormattedGraph]
+ [![FormattedGraph]][formattedgraph]
- [FormattedGraph]: ../../assets/user_guides/components/formatted_graph.png
+[formattedgraph]: ../../assets/user_guides/components/formatted_graph.png
+[graph]: ../../assets/user_guides/components/graph.png
diff --git a/vizro-core/docs/pages/user-guides/install.md b/vizro-core/docs/pages/user-guides/install.md
index 4d4c01239..6a07911e5 100644
--- a/vizro-core/docs/pages/user-guides/install.md
+++ b/vizro-core/docs/pages/user-guides/install.md
@@ -8,8 +8,8 @@ We recommend that you create a virtual environment for each Vizro project you wo
## Prerequisites to working locally
-* **Python**: Vizro supports macOS, Linux, and Windows. It works with Python 3.9 and later.
-* **Virtual environment**: You specify the version of Python to use with Vizro when you set up the virtual environment. See the following references to learn more about [Python virtual environments](https://realpython.com/python-virtual-environments-a-primer/), [Conda virtual environments](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#starting-conda) or [watch an explainer video about them](https://youtu.be/YKfAwIItO7M).
+- **Python**: Vizro supports macOS, Linux, and Windows. It works with Python 3.9 and later.
+- **Virtual environment**: You specify the version of Python to use with Vizro when you set up the virtual environment. See the following references to learn more about [Python virtual environments](https://realpython.com/python-virtual-environments-a-primer/), [Conda virtual environments](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#starting-conda) or [watch an explainer video about them](https://youtu.be/YKfAwIItO7M).
### How to create a virtual environment for your Vizro project
diff --git a/vizro-core/docs/pages/user-guides/kedro-data-catalog.md b/vizro-core/docs/pages/user-guides/kedro-data-catalog.md
index 0e2b0954e..ce4b060fa 100644
--- a/vizro-core/docs/pages/user-guides/kedro-data-catalog.md
+++ b/vizro-core/docs/pages/user-guides/kedro-data-catalog.md
@@ -3,6 +3,7 @@
This page describes how to integrate Vizro with [Kedro](https://docs.kedro.org/en/stable/index.html), an open-source Python framework to create reproducible, maintainable, and modular data science code. For Pandas datasets registered in a Kedro data catalog, Vizro provides a convenient way to visualize them.
## Installation
+
If you already have Kedro installed then you do not need to install any extra dependencies. If you do not have Kedro installed then you should run:
```bash
@@ -10,7 +11,9 @@ pip install vizro[kedro]
```
## Use datasets from the Kedro Data Catalog
+
`vizro.integrations.kedro` provides functions to help generate and process a [Kedro Data Catalog](https://docs.kedro.org/en/stable/data/index.html). Given a Kedro Data Catalog `catalog`, the general pattern to add datasets into the Vizro data manager is:
+
```python
from vizro.integrations import kedro as kedro_integration
from vizro.managers import data_manager
@@ -25,15 +28,14 @@ This imports all datasets of type [`kedro_datasets.pandas`](https://docs.kedro.o
The `catalog` variable may have been created in a number of different ways:
1. Kedro project path. Vizro exposes a helper function `vizro.integrations.kedro.catalog_from_project` to generate a `catalog` given the path to a Kedro project.
-2. [Kedro Jupyter session](https://docs.kedro.org/en/stable/notebooks_and_ipython/kedro_and_notebooks.html). This automatically exposes `catalog`.
-3. Data Catalog configuration file (`catalog.yaml`). This can create a `catalog` entirely independently of a Kedro project using [`kedro.io.DataCatalog.from_config`](https://docs.kedro.org/en/stable/kedro.io.DataCatalog.html#kedro.io.DataCatalog.from_config).
+1. [Kedro Jupyter session](https://docs.kedro.org/en/stable/notebooks_and_ipython/kedro_and_notebooks.html). This automatically exposes `catalog`.
+1. Data Catalog configuration file (`catalog.yaml`). This can create a `catalog` entirely independently of a Kedro project using [`kedro.io.DataCatalog.from_config`](https://docs.kedro.org/en/stable/kedro.io.DataCatalog.html#kedro.io.DataCatalog.from_config).
The full code for these different cases is given below.
!!! example "Import a Kedro Data Catalog into the Vizro data manager"
-
=== "app.py (Kedro project path)"
- ```py
+ ```python
from vizro.integrations import kedro as kedro_integration
from vizro.managers import data_manager
@@ -43,16 +45,18 @@ The full code for these different cases is given below.
for dataset_name, dataset in kedro_integration.datasets_from_catalog(catalog).items():
data_manager[dataset_name] = dataset
```
+
=== "app.ipynb (Kedro Jupyter session)"
- ```py
+ ```python
from vizro.managers import data_manager
for dataset_name, dataset in kedro_integration.datasets_from_catalog(catalog).items():
data_manager[dataset_name] = dataset
```
+
=== "app.py (Data Catalog configuration file)"
- ```py
+ ```python
from kedro.io import DataCatalog
import yaml
diff --git a/vizro-core/docs/pages/user-guides/layouts.md b/vizro-core/docs/pages/user-guides/layouts.md
index 8361560db..af66ec301 100644
--- a/vizro-core/docs/pages/user-guides/layouts.md
+++ b/vizro-core/docs/pages/user-guides/layouts.md
@@ -3,11 +3,10 @@
The [`Page`][vizro.models.Page] model accepts a `layout` argument that enables custom arrangement of charts and components on the screen. This guide shows how to customize the grid specifications in the [`Layout`][vizro.models.Layout].
## The default layout
-The `layout` argument of the [`Page`][vizro.models.Page] model is optional. If no layout is specified, all charts/components are automatically [**stacked vertically**](layouts.md#vertical-and-horizontal-stacking) on the page in one column.
-If you are happy with that arrangement, you can create your charts/components without providing a [`Layout`][vizro.models.Layout].
-!!! example "Default Layout"
+The `layout` argument of the [`Page`][vizro.models.Page] model is optional. If no layout is specified, all charts/components are automatically [**stacked vertically**](layouts.md#vertical-and-horizontal-stacking) on the page in one column. If you are happy with that arrangement, you can create your charts/components without providing a [`Layout`][vizro.models.Layout].
+!!! example "Default Layout"
=== "app.py"
```{.python pycafe-link}
from vizro import Vizro
@@ -23,35 +22,33 @@ If you are happy with that arrangement, you can create your charts/components wi
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- title: two_left
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ title: two_left
```
- === "Result"
- [![Layout]][Layout]
-
- [Layout]: ../../assets/user_guides/layout/two_left.png
-
+ === "Result"
+ [![Layout]][layout]
## Configure the grid
+
To customize the grid arrangement, configure the `grid` parameter of the [`Layout`][vizro.models.Layout] model.
The example below shows an example of a valid `grid`:
```python title="Basic example"
-grid = [[0, 1],
- [0, 2]]
+grid = [[0, 1], [0, 2]]
```
- The `grid` must be provided as `list[list[int]]` (for example, `grid = [[0, 1], [0, 2]]`).
@@ -64,16 +61,12 @@ grid = [[0, 1],
- The area spanned by a chart/component in the grid must be rectangular.
- The grid can be arbitrarily large, allowing arbitrarily granular control of the grid.
-
## Vertical and horizontal stacking
+
As described above, when no `Layout` is specified, components are presented **vertically** as a single-column stack. If you have three components, the default `Layout.grid` will be as follows, with three equally sized rows, each containing a component spanning the entire width:
```python title="Vertical stacking"
-grid = [
- [0],
- [1],
- [2]
- ]
+grid = [[0], [1], [2]]
```
To present components **horizontally** in one row:
@@ -89,8 +82,8 @@ This defines a single row that occupies the entire width and height, divided int
## Grid - basic example
-!!! example "Grid Arrangement - Basic Example"
+!!! example "Grid Arrangement - Basic Example"
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -109,39 +102,37 @@ This defines a single row that occupies the entire width and height, divided int
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- - text: |
- # Component 2
- type: card
- layout:
- grid: [[0, 1], [0, 2]]
- title: one_left_two_right
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ layout:
+ grid: [[0, 1], [0, 2]]
+ title: one_left_two_right
```
- === "Result"
- [![Grid]][Grid]
- [Grid]: ../../assets/user_guides/layout/one_left_two_right.png
+ === "Result"
+ [![Grid]][grid]
## Grid - advanced example
If you want to divide the grid into subgrids with finer control over these, you can use [`Containers`](container.md). See our section on [when to use `Containers` vs. `Page.layout`](container.md#when-to-use-containers) for more information.
-The `Layout` provides full control over the arrangement of top-level components within a page,
-allowing arbitrarily granular control of the grid by creating larger grids.
+The `Layout` provides full control over the arrangement of top-level components within a page, allowing arbitrarily granular control of the grid by creating larger grids.
!!! example "Grid Arrangement - Advanced Example"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -208,6 +199,7 @@ allowing arbitrarily granular control of the grid by creating larger grids.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -260,44 +252,44 @@ allowing arbitrarily granular control of the grid by creating larger grids.
grid: [[0, 1, 3, 4], [2, 2, 3, 4]]
title: Custom Layout - Advanced Example
```
- === "Result"
- [![GridAdv]][GridAdv]
- [GridAdv]: ../../assets/user_guides/layout/grid_advanced.png
+ === "Result"
+ [![GridAdv]][gridadv]
## Custom layout examples
+
Here is a reference table of example layouts:
+
one row with one component, second row with two components stacked horizontally
-| Layout needed | Grid | Code |
-|--------------------------------|----------------------------|-------------------------------------------------------------------------------------|
-| 
| ![layout=vm.Layout(grid=[[0]])](../../../assets/user_guides/layout/1l_grid.png)
| `layout=vm.Layout(grid=[[0]])` |
-| 
| 
| `layout=vm.Layout(grid=[[0],[1]])` |
-| 
| ![layout=vm.Layout(grid=[[0],[1]])](../../../assets/user_guides/layout/2t_grid.png)
| `layout=vm.Layout(grid=[[0,1]])` |
-| 
| ![layout=vm.Layout(grid=[[0],[1],[2]]](../../../assets/user_guides/layout/3l_grid.png)
| `layout=vm.Layout(grid=[[0],[1],[2]])` or
`layout=None` |
-| 
| ![layout=vm.Layout(grid=[[0,1],[0,2]])](../../../assets/user_guides/layout/1l_2r_grid.png)
| `layout=vm.Layout(grid=[[0,1],[0,2]])` |
-| 
| ![layout=vm.Layout(grid=[[0,0],[1,2]])](../../../assets/user_guides/layout/1t_2b_grid.png)
| `layout=vm.Layout(grid=[[0,0],[1,2]])` |
-| 
| ![layout=vm.Layout(grid=[[0,1],[2,2]])](../../../assets/user_guides/layout/2t_1b_grid.png)
| `layout=vm.Layout(grid=[[0,1],[2,2]])` |
-| 
| ![layout=vm.Layout(grid=[[0,1],[0,2],[0,3]])](../../../assets/user_guides/layout/1l_3r_grid.png)
| `layout=vm.Layout(grid=[[0,1],[0,2],[0,3]])` |
-| 
| ![layout=vm.Layout(grid=[[0,1],[2,3]])](../../../assets/user_guides/layout/2t_2b_grid.png)
| `layout=vm.Layout(grid=[[0,1],[2,3]])` |
-| 
| ![layout=vm.Layout(grid=[[0,3],[1,3],[2,3]])](../../../assets/user_guides/layout/3l_1r_grid.png)
| `layout=vm.Layout(grid=[[0,3],[1,3],[2,3]])` |
-| 
| ![layout=vm.Layout(grid=[[0,0,0],[1,2,3]])](../../../assets/user_guides/layout/1t_3b_grid.png)
| `layout=vm.Layout(grid=[[0,0,0],[1,2,3]])` |
-| 
| ![layout=vm.Layout(grid=[[0,1,2],[3,3,3]])](../../../assets/user_guides/layout/3t_1b_grid.png)
| `layout=vm.Layout(grid=[[0,1,2],[3,3,3]])` |
+| Layout needed | Grid | Code |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| | | `layout=vm.Layout(grid=[[0]])` |
+| | | `layout=vm.Layout(grid=[[0],[1]])` |
+| | | `layout=vm.Layout(grid=[[0,1]])` |
+| | | `layout=vm.Layout(grid=[[0],[1],[2]])` or
`layout=None` |
+| | | `layout=vm.Layout(grid=[[0,1],[0,2]])` |
+| | | `layout=vm.Layout(grid=[[0,0],[1,2]])` |
+| | | `layout=vm.Layout(grid=[[0,1],[2,2]])` |
+| | | `layout=vm.Layout(grid=[[0,1],[0,2],[0,3]])` |
+| | | `layout=vm.Layout(grid=[[0,1],[2,3]])` |
+| | | `layout=vm.Layout(grid=[[0,3],[1,3],[2,3]])` |
+| | | `layout=vm.Layout(grid=[[0,0,0],[1,2,3]])` |
+| | | `layout=vm.Layout(grid=[[0,1,2],[3,3,3]])` |
## Add empty sections to the grid
+
One approach to organize the dashboard's layout involves integrating empty sections by specifying `-1` within the grid layout.
```python title="Example"
-grid = [[0, 1, -1],
- [0, 2, -1]]
+grid = [[0, 1, -1], [0, 2, -1]]
```
!!! example "Adding Empty Spaces"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -316,38 +308,38 @@ grid = [[0, 1, -1],
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- - text: |
- # Component 2
- type: card
- layout:
- grid: [[0, 1, -1], [0, 2, -1]]
- title: Adding empty spaces
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ layout:
+ grid: [[0, 1, -1], [0, 2, -1]]
+ title: Adding empty spaces
```
- === "Result"
- [![GridEmpty]][GridEmpty]
- [GridEmpty]: ../../assets/user_guides/layout/layout_empty_spaces.png
+ === "Result"
+ [![GridEmpty]][gridempty]
## Control the scroll behavior
+
By default, the grid fits all charts/components on the screen. This can lead to distortions such that the chart/component looks squashed. To control the scroll behavior, you can specify the following:
- `row_min_height`: Sets a chart/component's minimum height. Defaults to 0px.
- `col_min_width`: Sets a chart/component's minimum width. Defaults to 0px.
!!! example "Activate Scrolling"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -371,59 +363,63 @@ By default, the grid fits all charts/components on the screen. This can lead to
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- - text: |
- # Component 2
- type: card
- - text: |
- # Component 2
- type: card
- - text: |
- # Component 4
- type: card
- - text: |
- # Component 5
- type: card
- - text: |
- # Component 6
- type: card
- - text: |
- # Component 7
- type: card
- layout:
- grid: [[0], [1], [2], [3], [4], [5], [6], [7]]
- row_min_height: 240px
- title: Activate scrolling
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ - text: |
+ # Component 4
+ type: card
+ - text: |
+ # Component 5
+ type: card
+ - text: |
+ # Component 6
+ type: card
+ - text: |
+ # Component 7
+ type: card
+ layout:
+ grid: [[0], [1], [2], [3], [4], [5], [6], [7]]
+ row_min_height: 240px
+ title: Activate scrolling
```
- === "Result"
- [![GridScroll]][GridScroll]
-
- [GridScroll]: ../../assets/user_guides/layout/grid_scroll.png
+ === "Result"
+ [![GridScroll]][gridscroll]
## Further customization
-For further customization, such as changing the gap between row and column, refer to the
-documentation of the [`Layout`][vizro.models.Layout] model.
+
+For further customization, such as changing the gap between row and column, refer to the documentation of the [`Layout`][vizro.models.Layout] model.
## Alternative layout approaches
+
In general, any arbitrarily granular layout can already be achieved using [`Page.layout`](layouts.md) alone and is our recommended approach if you want to arrange components on a page with consistent row and/or column spacing.
!!! note "Alternative layout approaches: `Tabs` and `Containers`"
-
- [`Tabs`][vizro.models.Tabs] and [`Containers`][vizro.models.Container] provide an alternative approach to customize your page layout.
- For example, if you want to have more granular control and break the overall page grid into subgrids, see our [user guide on Containers](container.md).
+ [`Tabs`][vizro.models.Tabs] and [`Containers`][vizro.models.Container] offer an alternative approach to customize your page layout. For example, if you want to have more granular control and break the overall page grid into subgrids, see our [user guide on Containers](container.md).
If you want to display multiple containers on one page by putting them into the same screen space, and letting the user switch between them, see our [user guide on Tabs](tabs.md).
{ width="500" }
+
+[grid]: ../../assets/user_guides/layout/one_left_two_right.png
+[gridadv]: ../../assets/user_guides/layout/grid_advanced.png
+[gridempty]: ../../assets/user_guides/layout/layout_empty_spaces.png
+[gridscroll]: ../../assets/user_guides/layout/grid_scroll.png
+[layout]: ../../assets/user_guides/layout/two_left.png
diff --git a/vizro-core/docs/pages/user-guides/navigation.md b/vizro-core/docs/pages/user-guides/navigation.md
index 41c6bb9dc..75a661470 100644
--- a/vizro-core/docs/pages/user-guides/navigation.md
+++ b/vizro-core/docs/pages/user-guides/navigation.md
@@ -2,8 +2,7 @@
This guide shows you how to use and customize the navigation that appears on the left of your dashboard.
-The [`Dashboard`][vizro.models.Dashboard] model accepts a `navigation` argument, where you can enter a [`Navigation`][vizro.models.Navigation] model. This enables you to group pages together and customize how they appear in your navigation.
-The dashboard includes a collapsible side panel that users can minimize or expand by a button click. The collapse button, located in the top right corner of the side panel, is visible by default for user convenience.
+The [`Dashboard`][vizro.models.Dashboard] model accepts a `navigation` argument, where you can enter a [`Navigation`][vizro.models.Navigation] model. This enables you to group pages together and customize how they appear in your navigation. The dashboard includes a collapsible side panel that users can minimize or expand by a button click. The collapse button, located in the top right corner of the side panel, is visible by default for user convenience.
## Use the default navigation
@@ -56,8 +55,8 @@ By default, if the `navigation` argument is not specified, Vizro creates a navig
type: graph
title: My first page
- components:
- - text: My text here
- type: card
+ - text: My text here
+ type: card
title: My second page
- components:
- figure:
@@ -69,10 +68,9 @@ By default, if the `navigation` argument is not specified, Vizro creates a navig
type: graph
title: My third page
```
- === "Result"
- [![DefaultNavigation]][DefaultNavigation]
- [DefaultNavigation]: ../../assets/user_guides/navigation/default_navigation.png
+ === "Result"
+ [![DefaultNavigation]][defaultnavigation]
## Include a subset of pages
@@ -132,17 +130,15 @@ To include only some of your dashboard pages in your navigation then list them i
- My first page
- My second page
```
- === "Result"
- [![OnlySomePages]][OnlySomePages]
- [OnlySomePages]: ../../assets/user_guides/navigation/only_some_pages.png
+ === "Result"
+ [![OnlySomePages]][onlysomepages]
## Group pages
You can also group your pages together by specifying `pages` as a dictionary:
!!! example "Grouping pages"
-
=== "snippet.py"
```py
# page_1, page_2, page_3 defined as in default example
@@ -154,7 +150,6 @@ You can also group your pages together by specifying `pages` as a dictionary:
```
=== "app.py"
-
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -187,6 +182,7 @@ You can also group your pages together by specifying `pages` as a dictionary:
)
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -200,18 +196,15 @@ You can also group your pages together by specifying `pages` as a dictionary:
Group B:
- My third page
```
- === "Result"
- [![GroupedNavigation]][GroupedNavigation]
-
- [GroupedNavigation]: ../../assets/user_guides/navigation/grouped_navigation.png
+ === "Result"
+ [![GroupedNavigation]][groupednavigation]
## Use a navigation bar with icons
Another way to group together pages in the navigation is to use a [`NavBar`][vizro.models.NavBar] with icons. The simplest way to use this is to change the `nav_selector` specified in [`Navigation`][vizro.models.Navigation]:
!!! example "Using `NavBar`"
-
=== "snippet.py"
```py
# page_1, page_2, page_3 defined as in default example
@@ -223,8 +216,8 @@ Another way to group together pages in the navigation is to use a [`NavBar`][viz
)
Vizro().build(dashboard).run()
```
- === "app.py"
+ === "app.py"
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -276,14 +269,11 @@ Another way to group together pages in the navigation is to use a [`NavBar`][viz
nav_selector:
type: nav_bar
```
- === "Result"
- [![NavBar]][NavBar]
-
- [NavBar]: ../../assets/user_guides/navigation/nav_bar.png
+ === "Result"
+ [![NavBar]][navbar]
-Here, the first level of the navigation hierarchy ("Group A" and "Group B") is represented by an icon in a navigation bar, and the second level of the navigation (the pages) is represented by an accordion.
-By default, the set of icons used are the [`filter` icons from the Google Material icons library](https://fonts.google.com/icons?icon.query=filter). The icon label ("Group A" and "Group B") appears as a tooltip on hovering over the icon.
+Here, the first level of the navigation hierarchy ("Group A" and "Group B") is represented by an icon in a navigation bar, and the second level of the navigation (the pages) is represented by an accordion. By default, the set of icons used are the [`filter` icons from the Google Material icons library](https://fonts.google.com/icons?icon.query=filter). The icon label ("Group A" and "Group B") appears as a tooltip on hovering over the icon.
## Customize the navigation bar
@@ -314,7 +304,6 @@ The same configuration for [grouping pages](#group-pages) applies inside a `NavL
```
=== "app.py"
-
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -375,10 +364,9 @@ The same configuration for [grouping pages](#group-pages) applies inside a `NavL
Group B:
- My third page
```
- === "Result"
- [![AccordionInsideNavBar]][AccordionInsideNavBar]
- [AccordionInsideNavBar]: ../../assets/user_guides/navigation/accordion_inside_nav_bar.png
+ === "Result"
+ [![AccordionInsideNavBar]][accordioninsidenavbar]
You can alter the icons used by specifying the name of the icon in the [Google Material icons library](https://fonts.google.com/icons):
@@ -402,8 +390,8 @@ You can alter the icons used by specifying the name of the icon in the [Google M
),
)
```
- === "app.py"
+ === "app.py"
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -468,7 +456,13 @@ You can alter the icons used by specifying the name of the icon in the [Google M
pages:
- My third page
```
- === "Result"
- [![CustomIcons]][CustomIcons]
- [CustomIcons]: ../../assets/user_guides/navigation/custom_icons.png
+ === "Result"
+ [![CustomIcons]][customicons]
+
+[accordioninsidenavbar]: ../../assets/user_guides/navigation/accordion_inside_nav_bar.png
+[customicons]: ../../assets/user_guides/navigation/custom_icons.png
+[defaultnavigation]: ../../assets/user_guides/navigation/default_navigation.png
+[groupednavigation]: ../../assets/user_guides/navigation/grouped_navigation.png
+[navbar]: ../../assets/user_guides/navigation/nav_bar.png
+[onlysomepages]: ../../assets/user_guides/navigation/only_some_pages.png
diff --git a/vizro-core/docs/pages/user-guides/pages.md b/vizro-core/docs/pages/user-guides/pages.md
index 7ae944e9b..71e01e9f9 100644
--- a/vizro-core/docs/pages/user-guides/pages.md
+++ b/vizro-core/docs/pages/user-guides/pages.md
@@ -1,7 +1,6 @@
# How to use pages
-This guide shows you how to add pages to your dashboard and customize the URL paths if needed.
-A [`Page`][vizro.models.Page] lets you place and arrange your dashboard content (for example, chart/components, tables, and text)
-and configure your dashboard interactions (such as filters and parameters).
+
+This guide shows you how to add pages to your dashboard and customize the URL paths if needed. A [`Page`][vizro.models.Page] lets you place and arrange your dashboard content (for example, chart/components, tables, and text) and configure your dashboard interactions (such as filters and parameters).
The [`Dashboard`][vizro.models.Dashboard] model accepts the `pages` argument, where you can insert your [`Page`][vizro.models.Page].
@@ -10,19 +9,19 @@ The [`Dashboard`][vizro.models.Dashboard] model accepts the `pages` argument, wh
A [`Page`][vizro.models.Page] is split up into four main containers:
1. The **navigation container** where you can customize your `navigation` (see [Dashboard](dashboard.md) and [Navigation](navigation.md) for more information). Note that the navigation container needs to be configured via the Dashboard.
-2. The **control container** where you can add your `controls` (see [Filters](filters.md) or [Parameters](parameters.md)) to interact with the dashboard
-3. The **page header** that contains the page title and the theme toggle switch button
-4. The **component container** where you can add your [components](components.md) to visualize your data
+1. The **control container** where you can add your `controls` (see [Filters](filters.md) or [Parameters](parameters.md)) to interact with the dashboard
+1. The **page header** that contains the page title and the theme toggle switch button
+1. The **component container** where you can add your [components](components.md) to visualize your data
To create and add a page to your dashboard, do the following steps:
1. Set a `title` for your [`Page`][vizro.models.Page]
-2. Configure your `components`, see our guide on the [various options](components.md)
-3. (optional) Configure your `controls` , see our guides on [Filters](filters.md) and [Parameters](parameters.md)
-4. (optional) Configure your `layout` , see our guide on [Layouts](layouts.md)
-5. (optional) Give a `description` of your `Page` to the app's [meta tags](https://metatags.io/)
+1. Configure your `components`, see our guide on the [various options](components.md)
+1. (optional) Configure your `controls` , see our guides on [Filters](filters.md) and [Parameters](parameters.md)
+1. (optional) Configure your `layout` , see our guide on [Layouts](layouts.md)
+1. (optional) Give a `description` of your `Page` to the app's [meta tags](https://metatags.io/)
!!! example "Page"
=== "app.py"
@@ -51,51 +50,47 @@ To create and add a page to your dashboard, do the following steps:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: sunburst
- path: ['continent', 'country']
- values: pop
- color: lifeExp
- data_frame: gapminder
- id: sunburst
- type: graph
- controls:
- - column: continent
- targets:
- - sunburst
- type: filter
- - selector:
- options: ['lifeExp', 'pop']
- title: Color
- type: radio_items
- targets:
- - sunburst.color
- type: parameter
- title: Page Title
- description: "Longer description of the page content"
+ - components:
+ - figure:
+ _target_: sunburst
+ path: [continent, country]
+ values: pop
+ color: lifeExp
+ data_frame: gapminder
+ id: sunburst
+ type: graph
+ controls:
+ - column: continent
+ targets: [sunburst]
+ type: filter
+ - selector:
+ options: [lifeExp, pop]
+ title: Color
+ type: radio_items
+ targets: [sunburst.color]
+ type: parameter
+ title: Page Title
+ description: Longer description of the page content
```
- === "Result"
- [![Page]][Page]
- [Page]: ../../assets/user_guides/pages/page_sunburst.png
+ === "Result"
+ [![Page]][page]
An accordion page selector is automatically added to your dashboard in the top-left of the control container for through the different pages. It will not be added if your dashboard consists of only one page.
You can additionally navigate through the different pages by going directly to the relevant page URL (more details in next section).
-
## Customize the page URL
-By default, the page URL is automatically generated based on the `id` of the page. For example, if `id="This is my first page"`
-the generated page URL will be `path=this-is-my-first-page`. You can then access the page via `localhost:/this-is-my-first-page`.
-Note that the page `id` defaults to be the same as the page `title` if not set.
-If you have multiple pages with the same `title` then you must assign a unique `id`.
+By default, the page URL is automatically generated based on the `id` of the page. For example, if `id="This is my first page"` the generated page URL will be `path=this-is-my-first-page`. You can then access the page via `localhost:/this-is-my-first-page`.
+
+Note that the page `id` defaults to be the same as the page `title` if not set. If you have multiple pages with the same `title` then you must assign a unique `id`.
The first page always has the URL prefix `/` assigned. A custom URL can, therefore, not be created for the first page.
@@ -137,39 +132,40 @@ To customize the page URL, pass a valid URL name to the `path` argument of [`Pag
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- Commodi repudiandae consequuntur voluptatum.
- type: card
- title: Page 1
- - components:
- - figure:
- _target_: sunburst
- path: ['continent', 'country']
- values: pop
- color: lifeExp
- data_frame: gapminder
- id: sunburst
- type: graph
- controls:
- - column: continent
- targets:
- - sunburst
- type: filter
- - selector:
- options: ['lifeExp', 'pop']
- title: Color
- type: radio_items
- targets:
- - sunburst.color
- type: parameter
- title: Page 2
- path: my-custom-url
+ - components:
+ - text: |
+ Commodi repudiandae consequuntur voluptatum.
+ type: card
+ title: Page 1
+ - components:
+ - figure:
+ _target_: sunburst
+ path: [continent, country]
+ values: pop
+ color: lifeExp
+ data_frame: gapminder
+ id: sunburst
+ type: graph
+ controls:
+ - column: continent
+ targets: [sunburst]
+ type: filter
+ - selector:
+ options: [lifeExp, pop]
+ title: Color
+ type: radio_items
+ targets: [sunburst.color]
+ type: parameter
+ title: Page 2
+ path: my-custom-url
```
You can now access the first page via `localhost:/` and the second page via `localhost:/my-custom-url`.
+
+[page]: ../../assets/user_guides/pages/page_sunburst.png
diff --git a/vizro-core/docs/pages/user-guides/parameters.md b/vizro-core/docs/pages/user-guides/parameters.md
index bb39a7a0c..c82707d4a 100644
--- a/vizro-core/docs/pages/user-guides/parameters.md
+++ b/vizro-core/docs/pages/user-guides/parameters.md
@@ -9,8 +9,8 @@ The [`Page`][vizro.models.Page] model accepts the `controls` argument, where you
To add a parameter to your page, do the following:
1. add the [`Parameter`][vizro.models.Parameter] model into the `controls` argument of the [`Page`][vizro.models.Page] model.
-2. add the `targets` argument
-3. add a selector model to the `selector` argument.
+1. add the `targets` argument
+1. add a selector model to the `selector` argument.
In the `targets` argument, you can specify the component and function argument that the parameter should be applied to in the form of `.` (for example, `scatter_chart.title`).
@@ -48,6 +48,7 @@ Unlike for the [`Filter`][vizro.models.Filter] model, you also have to configure
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -64,18 +65,17 @@ Unlike for the [`Filter`][vizro.models.Filter] model, you also have to configure
type: graph
controls:
- selector:
- options: ["My scatter chart", "A better title!", "Another title..."]
- multi: False
+ options: [My scatter chart, A better title!, Another title...]
+ multi: false
type: dropdown
targets:
- scatter_chart.title
type: parameter
title: My first page
```
- === "Result"
- [![Parameter]][Parameter]
- [Parameter]: ../../assets/user_guides/control/control4.png
+ === "Result"
+ [![Parameter]][parameter]
If you would like to pass `None` as a parameter and make a parameter optional, you can specify the string `"NONE"` in the `options` or `value` field.
@@ -133,6 +133,7 @@ If you want to change nested parameters, you can specify the `targets` argument
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -146,7 +147,7 @@ If you want to change nested parameters, you can specify the `targets` argument
y: sepal_length
size: petal_length
color: species
- color_discrete_map: {"setosa": "#00b4ff", "versicolor": "#ff9222"}
+ color_discrete_map: {setosa: '#00b4ff', versicolor: '#ff9222'}
id: scatter_chart
type: graph
- figure:
@@ -155,23 +156,22 @@ If you want to change nested parameters, you can specify the `targets` argument
x: sepal_width
y: sepal_length
color: species
- color_discrete_map: {"setosa": "#00b4ff", "versicolor": "#ff9222"}
+ color_discrete_map: {setosa: '#00b4ff', versicolor: '#ff9222'}
id: bar_chart
type: graph
controls:
- selector:
- options: ["#ff5267", "#3949ab"]
+ options: ['#ff5267', '#3949ab']
value: #3949ab
- multi: False
+ multi: false
type: dropdown
- targets: ["scatter_chart.color_discrete_map.virginica", "bar_chart.color_discrete_map.virginica"]
+ targets: [scatter_chart.color_discrete_map.virginica, bar_chart.color_discrete_map.virginica]
type: parameter
title: My first page
```
- === "Result"
- [![Nested]][Nested]
- [Nested]: ../../assets/user_guides/control/control5.png
+ === "Result"
+ [![Nested]][nested]
In the above example, the object passed to the function argument `color_discrete_map` is a dictionary which maps the different flower species to fixed colors (for example, `{"virginica":"blue"}`). In this case, only the value `blue` should be changed instead of the entire dictionary. This can be achieved by specifying a target as `scatter.color_discrete_map.virginica`.
@@ -180,3 +180,6 @@ Note that in the above example, one parameter affects multiple targets.
## Dynamic data parameters
If you use [dynamic data](data.md/#dynamic-data) that can be updated while the dashboard is running then you can pass parameters to the dynamic data function to alter the data loaded into your dashboard. For detailed instructions, refer to the section on [parametrized data loading](data.md/#parametrize-data-loading).
+
+[nested]: ../../assets/user_guides/control/control5.png
+[parameter]: ../../assets/user_guides/control/control4.png
diff --git a/vizro-core/docs/pages/user-guides/run.md b/vizro-core/docs/pages/user-guides/run.md
index df52e8c14..028eb5027 100644
--- a/vizro-core/docs/pages/user-guides/run.md
+++ b/vizro-core/docs/pages/user-guides/run.md
@@ -15,7 +15,6 @@ Most of our examples have a link below the code, [Run and edit this code in PyCa
You can use [PyCafe](https://py.cafe/snippet/vizro/v1) snippet mode to experiment with your own Vizro dashboards by dropping code into a new project.
-
## Default built-in Flask development server
!!! example "Default built-in Flask development server"
@@ -38,9 +37,10 @@ You can use [PyCafe](https://py.cafe/snippet/vizro/v1) snippet mode to experimen
Vizro().build(dashboard).run()
```
+
1. create a Python file named `app.py`.
-2. type the command `python app.py` into your terminal.
-3. information below will be displayed in your terminal, go to [http://127.0.0.1:8050/](http://127.0.0.1:8050/).
+1. type the command `python app.py` into your terminal.
+1. information below will be displayed in your terminal, go to [http://127.0.0.1:8050/](http://127.0.0.1:8050/).
```
Dash is running on http://127.0.0.1:8050/
@@ -51,8 +51,7 @@ INFO:werkzeug:WARNING: This is a development server. Do not use it in a producti
```
!!! warning "In production"
-
- As per the above warning message, which is [further explained in the Flask documentation](https://flask.palletsprojects.com/en/3.0.x/deploying/), the Flask development server is intended for use only during local development and **should not** be used when deploying to production. Instead, you should instead use a production-ready solution such as [Gunicorn](#gunicorn).
+ The above warning message is [further explained in the Flask documentation](https://flask.palletsprojects.com/en/3.0.x/deploying/). The Flask development server is intended for use only during local development and **should not** be used when deploying to production. Instead, you should instead use a production-ready solution such as [Gunicorn](#gunicorn).
### Automatic reloading and debugging
@@ -64,11 +63,11 @@ Setting `debug=True` enables [Dash Dev Tools](https://dash.plotly.com/devtools).
In addition, some errors generated at run time can also be viewed via the browser console (for example in `Chrome` see `View > Developer > Developer Tools > Console`).
-
## Jupyter
+
The dashboard application can be launched in a Jupyter environment in `inline`, `external`, and `jupyterlab` mode.
-!!! example "Run in a Jupyter Notebook in inline mode"
+!!! example "Run in a Jupyter Notebook in inline mode"
=== "app.ipynb"
```py linenums="1"
from vizro import Vizro
@@ -87,16 +86,16 @@ The dashboard application can be launched in a Jupyter environment in `inline`,
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run(jupyter_mode="external")
```
+
- by default, the mode is set to `inline` in `run()` and the dashboard will be displayed inside your Jupyter environment.
- you can specify `jupyter_mode="external"` and a link will be displayed to direct you to the localhost where the dashboard is running.
- you can use tab mode by `jupyter_mode="tab"` to automatically open the app in a new browser
!!! note "Reloading and debugging"
-
Code reloading and hot reloading do not work within a Jupyter Notebook. Instead, there are two methods to reload the dashboard:
- * Restart the Jupyter kernel and re-run your notebook.
- * Add a cell containing `from vizro import Vizro; Vizro._reset()` to the top of your notebook and re-run it. With this method, there is no need to restart the Jupyter kernel.
+ - Restart the Jupyter kernel and re-run your notebook.
+ - Add a cell containing `from vizro import Vizro; Vizro._reset()` to the top of your notebook and re-run it. With this method, there is no need to restart the Jupyter kernel.
## Gunicorn
@@ -126,17 +125,18 @@ The dashboard application can be launched in a Jupyter environment in `inline`,
```
1. The Vizro `app` object is a WSGI application that exposes the underlying Flask app; this will be used by Gunicorn.
- 2. Enable the same app to still be run using the built-in Flask server with `python app.py` for development purposes.
+ 1. Enable the same app to still be run using the built-in Flask server with `python app.py` for development purposes.
To run using Gunicorn with four worker processes, execute
+
```bash
gunicorn app:app --workers 4
```
+
in the command line. For more Gunicorn configuration options, refer to [Gunicorn documentation](https://docs.gunicorn.org/).
!!! warning "In production"
-
- If your dashboard uses [dynamic data](data.md#dynamic-data) that can be refreshed while the dashboard is running then you should [configure your data manager cache](data.md#configure-cache) to use a backend that supports multiple processes.
+ If your dashboard uses [dynamic data](data.md#dynamic-data) that can be refreshed while the dashboard is running then you should [configure your data manager cache](data.md#configure-cache) to use a back end that supports multiple processes.
## Deployment
@@ -149,6 +149,6 @@ Internally, `app = Vizro()` contains a Flask app in `app.dash.server`. However,
[`Vizro`][vizro.Vizro] accepts `**kwargs` that are passed through to `Dash`. This enables you to configure the underlying Dash app using the same [arguments that are available](https://dash.plotly.com/reference#dash.dash) in `Dash`. For example, in a deployment context, these arguments may be useful:
-- `url_base_pathname`: serve your Vizro app at a specific path rather than at the domain root. For example, if you host your dashboard at http://www.example.com/my_dashboard/ then you would set `url_base_pathname="/my_dashboard/"` or an environment variable `DASH_URL_BASE_PATHNAME="/my_dashboard/"`.
+- `url_base_pathname`: serve your Vizro app at a specific path rather than at the domain root. For example, if you host your dashboard at `http://www.example.com/my_dashboard/` then you would set `url_base_pathname="/my_dashboard/"` or an environment variable `DASH_URL_BASE_PATHNAME="/my_dashboard/"`.
- `serve_locally`: set to `False` to [serve Dash component libraries from a Content Delivery Network (CDN)](https://dash.plotly.com/external-resources#serving-dash's-component-libraries-locally-or-from-a-cdn), which reduces load on the server and can improve performance. Vizro uses [jsDeliver](https://www.jsdelivr.com/) as a CDN for CSS and JavaScript sources.
- `assets_external_path`: when `serve_locally=False`, you can also set `assets_external_path` or an environment variable `DASH_ASSETS_EXTERNAL_PATH` to [serve your own assets from a CDN](https://dash.plotly.com/external-resources#load-assets-from-a-folder-hosted-on-a-cdn).
diff --git a/vizro-core/docs/pages/user-guides/selectors.md b/vizro-core/docs/pages/user-guides/selectors.md
index 10481d2ba..a1bd4be20 100644
--- a/vizro-core/docs/pages/user-guides/selectors.md
+++ b/vizro-core/docs/pages/user-guides/selectors.md
@@ -6,10 +6,7 @@ The [`Filter`][vizro.models.Filter] or the [`Parameter`][vizro.models.Parameter]
## Categorical selectors
-Within the categorical selectors, a clear distinction exists between multi-option and single-option selectors.
-For instance, the [`Checklist`][vizro.models.Checklist] functions as a multi-option selector by default while
-the [`RadioItem`][vizro.models.RadioItems] serves as a single-option selector by default. However, the
-[`Dropdown`][vizro.models.Dropdown] can function as both a multi-option or single-option selector.
+Within the categorical selectors, a clear distinction exists between multi-option and single-option selectors. For instance, the [`Checklist`][vizro.models.Checklist] functions as a multi-option selector by default while the [`RadioItem`][vizro.models.RadioItems] serves as a single-option selector by default. However, the [`Dropdown`][vizro.models.Dropdown] can function as both a multi-option or single-option selector.
For more information, refer to the API reference of the selector, or the documentation of its underlying Dash component:
@@ -18,15 +15,12 @@ For more information, refer to the API reference of the selector, or the documen
- [`RadioItems`][vizro.models.RadioItems] based on [`dcc.RadioItems`](https://dash.plotly.com/dash-core-components/radioitems)
!!! note
-
- When configuring the `options` of the categorical selectors, you can either provide:
+ When configuring the `options` of the categorical selectors, you can either give:
- a list of values `options = ['Value A', 'Value B', 'Value C']`
- or a dictionary of label-value mappings `options=[{'label': 'True', 'value': True}, {'label': 'False', 'value': False}]`
- The later is required if you want to provide different display labels to your option values or in case you want to
- provide boolean values as options. In this case, you need to provide a string label for your boolean values as
- boolean values cannot be displayed properly as labels in the underlying Dash components.
+ The later is required if you want to provide different display labels to your option values or in case you want to provide boolean values as options. In this case, you need to provide a string label for your boolean values as boolean values cannot be displayed properly as labels in the underlying Dash components.
## Numerical selectors
@@ -36,11 +30,7 @@ For more information, refer to the API reference of the selector, or the documen
- [`RangeSlider`][vizro.models.RangeSlider] based on [`dcc.RangeSlider`](https://dash.plotly.com/dash-core-components/rangeslider)
!!! note
-
- When configuring the [`Slider`][vizro.models.Slider] and the [`RangeSlider`][vizro.models.RangeSlider] with float values, and using `step` with an integer value, you may notice
- unexpected behavior, such as the drag value being outside its indicated marks.
- To our knowledge, this is a current bug in the underlying [`dcc.Slider`](https://dash.plotly.com/dash-core-components/slider) and
- [`dcc.RangeSlider`](https://dash.plotly.com/dash-core-components/rangeslider) component, which you can circumvent by adapting the `step` size accordingly.
+ When configuring the [`Slider`][vizro.models.Slider] and the [`RangeSlider`][vizro.models.RangeSlider] with float values, and using `step` with an integer value, you may notice unexpected behavior, such as the drag value being outside its indicated marks. To our knowledge, this is a current bug in the underlying [`dcc.Slider`](https://dash.plotly.com/dash-core-components/slider) and [`dcc.RangeSlider`](https://dash.plotly.com/dash-core-components/rangeslider) component, which you can circumvent by adapting the `step` size as needed.
## Temporal selectors
@@ -49,7 +39,6 @@ For more information, refer to the API reference of the selector, or the documen
- [`DatePicker`][vizro.models.DatePicker] based on [`dmc.DateRangePicker`](https://www.dash-mantine-components.com/components/datepicker#daterangepicker) and [`dmc.DatePicker`](https://www.dash-mantine-components.com/components/datepicker)
!!! note
-
When the [`DatePicker`][vizro.models.DatePicker] is configured with `range=True` (the default), the underlying component is `dmc.DateRangePicker`. When `range=False` the underlying component is `dmc.DatePicker`.
When configuring the [`DatePicker`][vizro.models.DatePicker] make sure to provide your dates for `min`, `max` and `value` arguments in `"yyyy-mm-dd"` format or as `datetime` type (for example, `datetime.datetime(2024, 01, 01)`).
diff --git a/vizro-core/docs/pages/user-guides/table.md b/vizro-core/docs/pages/user-guides/table.md
index 19197c465..80e8e53dc 100755
--- a/vizro-core/docs/pages/user-guides/table.md
+++ b/vizro-core/docs/pages/user-guides/table.md
@@ -2,46 +2,32 @@
This guide shows you how to visualize tables in Vizro.
-There are two ways to visualize tables in Vizro, using either [AG Grid](#ag-grid) or [Dash DataTable](#dash-datatable).
-In general, [AG Grid](#ag-grid) is Vizro's recommended table implementation, but sometimes it may make sense to use the [Dash DataTable](#dash-datatable) instead.
+There are two ways to visualize tables in Vizro, using either [AG Grid](#ag-grid) or [Dash DataTable](#dash-datatable). In general, [AG Grid](#ag-grid) is Vizro's recommended table implementation, but sometimes it may make sense to use the [Dash DataTable](#dash-datatable) instead.
## Choose between AG Grid and Dash DataTable
-Vizro offers two models - the [`AgGrid`][vizro.models.AgGrid] model and the [`Table`][vizro.models.Table] model - for the above two approaches respectively.
-They both visualize tabular data in similar ways.
+Vizro offers two models - the [`AgGrid`][vizro.models.AgGrid] model and the [`Table`][vizro.models.Table] model - for the above two approaches respectively. They both visualize tabular data in similar ways.
-The main difference between the two is that the [`AgGrid`][vizro.models.AgGrid] model is based on Plotly's [Dash AG Grid](https://dash.plotly.com/dash-ag-grid) component,
-while the [`Table`][vizro.models.Table] model is based on the [Dash DataTable](https://dash.plotly.com/datatable) component.
-
-Both approaches have similar base features, and are configurable in similar ways. However, the AG Grid offers more advanced features out-of-the-box, is more customizable
-and also ships a powerful enterprise version. This is why it is Vizro's recommended table implementation. At the same time, the Dash DataTable can be used if developers are
-already familiar with it, or if some custom functionality is easier to implement using the Dash DataTable.
+The main difference between the two is that the [`AgGrid`][vizro.models.AgGrid] model is based on Plotly's [Dash AG Grid](https://dash.plotly.com/dash-ag-grid) component, while the [`Table`][vizro.models.Table] model is based on the [Dash DataTable](https://dash.plotly.com/datatable) component.
+Both approaches have similar base features, and are configurable in similar ways. However, the AG Grid offers more advanced features out-of-the-box, is more customizable and also ships a powerful enterprise version. This is why it is Vizro's recommended table implementation. At the same time, the Dash DataTable can be used if developers are already familiar with it, or if some custom functionality is easier to implement using the Dash DataTable.
## AG Grid
-[AG Grid](https://www.ag-grid.com/) is an interactive table/grid component designed for viewing, editing, and exploring large datasets. It
-is Vizro's recommended table implementation.
+[AG Grid](https://www.ag-grid.com/) is an interactive table/grid component designed for viewing, editing, and exploring large datasets. It is Vizro's recommended table implementation.
-The Vizro [`AgGrid`][vizro.models.AgGrid] model is based on the [Dash AG Grid](https://dash.plotly.com/dash-ag-grid), which is in turn based the
-original [Javascript implementation](https://www.ag-grid.com/).
+The Vizro [`AgGrid`][vizro.models.AgGrid] model is based on the [Dash AG Grid](https://dash.plotly.com/dash-ag-grid), which is in turn based the original [Javascript implementation](https://www.ag-grid.com/).
### Basic usage
To add a [`AgGrid`][vizro.models.AgGrid] to your page, do the following:
-1. Insert the [`AgGrid`][vizro.models.AgGrid] model into the `components` argument of the
-[`Page`][vizro.models.Page] model.
-2. Enter the `dash_ag_grid` function under the `figure` argument (imported via `from vizro.tables import dash_ag_grid`).
-
-The Vizro version of this AG Grid differs in one way from the original Dash AG Grid: it requires the user to pass a pandas DataFrame as the source of data.
-As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`. Most other [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments.
-Note that some defaults are set for some arguments (for example, for `columnDefs`) to help with styling and usability.
-Sometimes a parameter may not work because it requires a callback to function. In that case you can try [creating a custom AG Grid callable](custom-tables.md).
+1. Insert the [`AgGrid`][vizro.models.AgGrid] model into the `components` argument of the [`Page`][vizro.models.Page] model.
+1. Enter the `dash_ag_grid` function under the `figure` argument (imported via `from vizro.tables import dash_ag_grid`).
+The Vizro version of this AG Grid differs in one way from the original Dash AG Grid: it requires the user to pass a pandas DataFrame as the source of data. As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`. Most other [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments. Note that some defaults are set for some arguments (for example, for `columnDefs`) to help with styling and usability. Sometimes a parameter may not work because it requires a callback to function. In that case you can try [creating a custom AG Grid callable](custom-tables.md).
!!! example "Basic Dash AG Grid"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -59,29 +45,28 @@ Sometimes a parameter may not work because it requires a callback to function. I
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - figure:
- _target_: dash_ag_grid
- data_frame: gapminder
- type: ag_grid
- title: Default Dash AG Grid
+ - components:
+ - figure:
+ _target_: dash_ag_grid
+ data_frame: gapminder
+ type: ag_grid
+ title: Default Dash AG Grid
```
- === "Result"
- [![AGGrid]][AGGrid]
- [AGGrid]: ../../assets/user_guides/table/aggrid.png
+ === "Result"
+ [![AGGrid]][aggrid]
### Enable pagination
-Pagination is a visual alternative to using vertical scroll. It can also improve loading time if you have many rows.
-You can turn it on by setting `dashGridOptions={"pagination": True}`.
-!!! example "Basic Dash AG Grid"
+Pagination is a visual alternative to using vertical scroll. It can also improve loading time if you have many rows. You can turn it on by setting `dashGridOptions={"pagination": True}`.
+!!! example "Basic Dash AG Grid"
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -99,37 +84,34 @@ You can turn it on by setting `dashGridOptions={"pagination": True}`.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - figure:
- _target_: dash_ag_grid
- data_frame: gapminder
- dashGridOptions:
- pagination: true
- type: ag_grid
- title: Dash AG Grid with pagination
+ - components:
+ - figure:
+ _target_: dash_ag_grid
+ data_frame: gapminder
+ dashGridOptions:
+ pagination: true
+ type: ag_grid
+ title: Dash AG Grid with pagination
```
- === "Result"
- [![AGGrid]][AGGrid]
- [AGGrid]: ../../assets/user_guides/table/aggrid-pagination.png
+ === "Result"
+ [![AGGrid]][aggrid]
### Formatting columns
#### Numbers
-One of the most common tasks when working with tables is to format the columns so that displayed numbers are more readable.
-To do this, you can use the native functionality of [value formatters](https://dash.plotly.com/dash-ag-grid/value-formatters)
-or the Vizro pre-defined [custom cell data types](https://dash.plotly.com/dash-ag-grid/cell-data-types#providing-custom-cell-data-types) as shown below.
+One of the most common tasks when working with tables is to format the columns so that displayed numbers are more readable. To do this, you can use the native functionality of [value formatters](https://dash.plotly.com/dash-ag-grid/value-formatters) or the Vizro pre-defined [custom cell data types](https://dash.plotly.com/dash-ag-grid/cell-data-types#providing-custom-cell-data-types) as shown below.
The available custom cell types for Vizro are `dollar`, `euro`, `percent` and `numeric`.
-To use these, define your desired `` alongside the chosen `cellDataType` in
-the `columnDefs` argument of your `dash_ag_grid` function:
+To use these, define your desired `` alongside the chosen `cellDataType` in the `columnDefs` argument of your `dash_ag_grid` function:
```py
columnDefs = [{"field": "", "cellDataType": "euro"}]
@@ -138,7 +120,6 @@ columnDefs = [{"field": "", "cellDataType": "euro"}]
In the example below we select and format some columns of the gapminder data.
!!! example "AG Grid with formatted columns"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -168,6 +149,7 @@ In the example below we select and format some columns of the gapminder data.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -190,33 +172,23 @@ In the example below we select and format some columns of the gapminder data.
type: ag_grid
title: Example of AG Grid with formatted columns
```
- === "Result"
- [![AGGrid2]][AGGrid2]
- [AGGrid2]: ../../assets/user_guides/table/formatted_aggrid.png
+ === "Result"
+ [![AGGrid2]][aggrid2]
#### Dates
-For the [`AgGrid`][vizro.models.AgGrid] model to sort and filter dates correctly, the date must either be of
-string format `yyyy-mm-dd` (see [Dash AG Grid docs](https://dash.plotly.com/dash-ag-grid/date-filters#example:-date-filter))
-or a pandas datetime object. Any pandas datetime column will be transformed into the `yyyy-mm-dd` format automatically.
+For the [`AgGrid`][vizro.models.AgGrid] model to sort and filter dates correctly, the date must either be of string format `yyyy-mm-dd` (see [Dash AG Grid docs](https://dash.plotly.com/dash-ag-grid/date-filters#example:-date-filter)) or a pandas datetime object. Any pandas datetime column will be transformed into the `yyyy-mm-dd` format automatically.
#### Objects and strings
-No specific formatting is available for custom objects and strings, however you can make use of [Value Formatters](https://dash.plotly.com/dash-ag-grid/value-formatters)
-to format displayed strings automatically.
-
+No specific formatting is available for custom objects and strings, however you can make use of [Value Formatters](https://dash.plotly.com/dash-ag-grid/value-formatters) to format displayed strings automatically.
### Styling and changing the AG Grid
-As mentioned above, all [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments. Below you can find
-an example of a styled AG Grid where some conditional formatting is applied, and where the columns are editable, but
-not filterable or resizable. There are more ways to alter the grid beyond this showcase. AG Grid, like any other Vizro
-component, can be customized using custom CSS. You can find information in
-the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-selected-components).
+As mentioned above, all [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments. Below you can find an example of a styled AG Grid where some conditional formatting is applied, and where the columns are editable, but not filterable or resizable. There are more ways to alter the grid beyond this showcase. AG Grid, like any other Vizro component, can be customized using custom CSS. You can find information in the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-selected-components).
!!! example "Styled and modified Dash AG Grid"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -284,6 +256,7 @@ the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-select
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -299,28 +272,28 @@ the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-select
- field: year
- field: lifeExp
valueFormatter:
- function: "d3.format('.1f')(params.value)"
+ function: d3.format('.1f')(params.value)
- field: gdpPercap
valueFormatter:
- function: "d3.format('$,.1f')(params.value)"
+ function: d3.format('$,.1f')(params.value)
cellStyle:
styleConditions:
- condition: params.value < 1045
style:
- backgroundColor: "#ff9222"
+ backgroundColor: '#ff9222'
- condition: params.value >= 1045 && params.value <= 4095
style:
- backgroundColor: "#de9e75"
+ backgroundColor: '#de9e75'
- condition: params.value > 4095 && params.value <= 12695
style:
- backgroundColor: "#aaa9ba"
+ backgroundColor: '#aaa9ba'
- condition: params.value > 12695
style:
- backgroundColor: "#00b4ff"
+ backgroundColor: '#00b4ff'
- field: pop
type: rightAligned
valueFormatter:
- function: "d3.format(',.0f')(params.value)"
+ function: d3.format(',.0f')(params.value)
defaultColDef:
resizable: false
filter: false
@@ -329,10 +302,9 @@ the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-select
type: ag_grid
title: Example of a Dash AG Grid
```
- === "Result"
- [![AGGrid3]][AGGrid3]
- [AGGrid3]: ../../assets/user_guides/table/styled_aggrid.png
+ === "Result"
+ [![AGGrid3]][aggrid3]
If the available arguments are not sufficient, there is always the option to [create a custom AG Grid callable](custom-tables.md).
@@ -348,19 +320,14 @@ The Vizro [`Table`][vizro.models.Table] model is based on the [Dash DataTable](h
To add a [`Table`][vizro.models.Table] to your page, do the following:
-1. Insert the [`Table`][vizro.models.Table] model into the `components` argument of the
-[`Page`][vizro.models.Page] model.
-2. Enter the `dash_data_table` function under the `figure` argument (imported via `from vizro.tables import dash_data_table`).
-
+1. Insert the [`Table`][vizro.models.Table] model into the `components` argument of the [`Page`][vizro.models.Page] model.
+1. Enter the `dash_data_table` function under the `figure` argument (imported via `from vizro.tables import dash_data_table`).
-The Vizro version of this table differs in one way from the original table: it requires the user to pass a pandas DataFrame as the source of data.
-As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`.
+The Vizro version of this table differs in one way from the original table: it requires the user to pass a pandas DataFrame as the source of data. As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`.
-All other [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Note that we are
-setting some defaults for some arguments to help with styling.
+All other [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Note that we are setting some defaults for some arguments to help with styling.
!!! example "Dash DataTable"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -380,31 +347,29 @@ setting some defaults for some arguments to help with styling.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: dash_data_table
- data_frame: gapminder_2007
- title: Dash DataTable
- type: table
- title: Example of a Dash DataTable
+ - components:
+ - figure:
+ _target_: dash_data_table
+ data_frame: gapminder_2007
+ title: Dash DataTable
+ type: table
+ title: Example of a Dash DataTable
```
- === "Result"
- [![Table]][Table]
- [Table]: ../../assets/user_guides/table/table.png
+ === "Result"
+ [![Table]][table]
### Styling and changing the Dash DataTable
-As mentioned above, all [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Below you can find
-an example of a styled table where some conditional formatting is applied. There are many more ways to alter the table beyond this showcase.
+As mentioned above, all [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Below you can find an example of a styled table where some conditional formatting is applied. There are many more ways to alter the table beyond this showcase.
!!! example "Styled Dash DataTable"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -467,6 +432,7 @@ an example of a styled table where some conditional formatting is applied. There
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -504,12 +470,12 @@ an example of a styled table where some conditional formatting is applied. There
backgroundColor: dodgerblue
color: white
- if:
- filter_query: "{lifeExp} < 55"
+ filter_query: '{lifeExp} < 55'
column_id: lifeExp
- backgroundColor: "#85144b"
+ backgroundColor: '#85144b'
color: white
- if:
- filter_query: "{gdpPercap} > 10000"
+ filter_query: '{gdpPercap} > 10000'
column_id: gdpPercap
backgroundColor: green
color: white
@@ -524,26 +490,20 @@ an example of a styled table where some conditional formatting is applied. There
title: Dash DataTable
```
- === "Result"
- [![Table2]][Table2]
- [Table2]: ../../assets/user_guides/table/styled_table.png
+ === "Result"
+ [![Table2]][table2]
If the available arguments are not sufficient, there is always the option to create a [custom Dash DataTable](custom-tables.md).
-
## Add title, header, and footer
-The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] models accept a `title`, `header` and
-`footer` argument. This is useful for providing context to the data being displayed, or for adding a description of
-the data.
+The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] models accept a `title`, `header` and `footer` argument. This is useful for providing context to the data being displayed, or for adding a description of the data.
- **title**: Displayed as an [H3 header](https://dash.plotly.com/dash-html-components/h3), useful for summarizing the main topic or insight of the component.
- **header**: Accepts markdown text, ideal for extra descriptions, subtitles, or detailed data insights.
- **footer**: Accepts markdown text, commonly used for citing data sources, providing information on the last update, or adding disclaimers.
-
-
### Formatted AgGrid
!!! example "Formatted AgGrid"
@@ -571,30 +531,29 @@ the data.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: dash_ag_grid
- data_frame: gapminder_2007
- dashGridOptions:
- pagination: true
- title: Gapminder Data Insights
- header: |
- #### An Interactive Exploration of Global Health, Wealth, and Population
- footer: |
- SOURCE: **Plotly gapminder data set, 2024**
- type: ag_grid
- title: Formatted AgGrid
+ - components:
+ - figure:
+ _target_: dash_ag_grid
+ data_frame: gapminder_2007
+ dashGridOptions:
+ pagination: true
+ title: Gapminder Data Insights
+ header: |
+ #### An Interactive Exploration of Global Health, Wealth, and Population
+ footer: |
+ SOURCE: **Plotly gapminder data set, 2024**
+ type: ag_grid
+ title: Formatted AgGrid
```
- === "Result"
- [![FormattedGrid]][FormattedGrid]
-
- [FormattedGrid]: ../../assets/user_guides/components/formatted_aggrid.png
+ === "Result"
+ [![FormattedGrid]][formattedgrid]
### Formatted DataTable
@@ -623,24 +582,32 @@ the data.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: dash_data_table
- data_frame: gapminder_2007
- title: Gapminder Data Insights
- header: |
- #### An Interactive Exploration of Global Health, Wealth, and Population
- footer: |
- SOURCE: **Plotly gapminder data set, 2024**
- type: table
- title: Formatted DataTable
+ - components:
+ - figure:
+ _target_: dash_data_table
+ data_frame: gapminder_2007
+ title: Gapminder Data Insights
+ header: |
+ #### An Interactive Exploration of Global Health, Wealth, and Population
+ footer: |
+ SOURCE: **Plotly gapminder data set, 2024**
+ type: table
+ title: Formatted DataTable
```
- === "Result"
- [![FormattedTable]][FormattedTable]
- [FormattedTable]: ../../assets/user_guides/components/formatted_table.png
+ === "Result"
+ [![FormattedTable]][formattedtable]
+
+[aggrid]: ../../assets/user_guides/table/aggrid.png
+[aggrid2]: ../../assets/user_guides/table/formatted_aggrid.png
+[aggrid3]: ../../assets/user_guides/table/styled_aggrid.png
+[formattedgrid]: ../../assets/user_guides/components/formatted_aggrid.png
+[formattedtable]: ../../assets/user_guides/components/formatted_table.png
+[table]: ../../assets/user_guides/table/table.png
+[table2]: ../../assets/user_guides/table/styled_table.png
diff --git a/vizro-core/docs/pages/user-guides/tabs.md b/vizro-core/docs/pages/user-guides/tabs.md
index 09154177e..1811d0cac 100755
--- a/vizro-core/docs/pages/user-guides/tabs.md
+++ b/vizro-core/docs/pages/user-guides/tabs.md
@@ -1,8 +1,6 @@
# How to use tabs
-[`Tabs`][vizro.models.Tabs] organize and separate groups of related content in a dashboard, letting users switch between different sections or views.
-They are essentially a way of putting multiple [`Containers`][vizro.models.Container] in the same screen space, and letting the user switch between them.
-`Containers` enable the grouping of page components into sections and subsections. See our [user guide on `Containers`](container.md) for more information.
+[`Tabs`][vizro.models.Tabs] organize and separate groups of related content in a dashboard, letting users switch between different sections or views. They are essentially a way of putting multiple [`Containers`][vizro.models.Container] in the same screen space, and letting the user switch between them. `Containers` enable the grouping of page components into sections and subsections. See our [user guide on `Containers`](container.md) for more information.
{ width="400"}
@@ -16,14 +14,12 @@ This guide shows you how to use tabs to organize your `Containers` into subsecti
By using [`Tabs`][vizro.models.Tabs], the following applies:
- [`Filters`][vizro.models.Filter] affect all components on all tabs (opened and closed) of the page if not specified otherwise inside `Filter.targets`
-- The `title` of the [`Container`][vizro.models.Container] inserted into `Tabs.tabs` will be displayed as a tab label, and the title will be removed from the `Container`
-
+- The `title` of the [`Container`][vizro.models.Container] inserted into `Tabs.tabs` will be displayed as a tab label, and the title will be removed from the `Container`
To add [`Tabs`][vizro.models.Tabs] to your page, do the following:
1. Insert the [`Tabs`][vizro.models.Tabs] into the `components` argument of the [`Page`][vizro.models.Page]
-2. Insert your [`Containers`][vizro.models.Container] into the `tabs` argument of the [`Tabs`][vizro.models.Tabs]
-
+1. Insert your [`Containers`][vizro.models.Container] into the `tabs` argument of the [`Tabs`][vizro.models.Tabs]
!!! example "Tabs"
=== "app.py"
@@ -88,52 +84,53 @@ To add [`Tabs`][vizro.models.Tabs] to your page, do the following:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - tabs:
- - title: Tab I
- type: container
- components:
- - type: graph
- figure:
- _target_: bar
- data_frame: gapminder_2007
- title: Graph 1
- x: continent
- y: lifeExp
- color: continent
- - type: graph
- figure:
- _target_: box
- data_frame: gapminder_2007
- title: Graph 2
- x: continent
- y: lifeExp
- color: continent
- - title: Tab II
- type: container
- components:
- - type: graph
- figure:
- _target_: scatter
- data_frame: gapminder_2007
- title: Graph 3
- x: gdpPercap
- y: lifeExp
- size: pop
- color: continent
- type: tabs
+ components:
+ - type: tabs
+ tabs:
+ - title: Tab I
+ type: container
+ components:
+ - type: graph
+ figure:
+ _target_: bar
+ data_frame: gapminder_2007
+ title: Graph 1
+ x: continent
+ y: lifeExp
+ color: continent
+ - type: graph
+ figure:
+ _target_: box
+ data_frame: gapminder_2007
+ title: Graph 2
+ x: continent
+ y: lifeExp
+ color: continent
+ - title: Tab II
+ type: container
+ components:
+ - type: graph
+ figure:
+ _target_: scatter
+ data_frame: gapminder_2007
+ title: Graph 3
+ x: gdpPercap
+ y: lifeExp
+ size: pop
+ color: continent
controls:
- - type: filter
- column: continent
+ - type: filter
+ column: continent
title: Tabs
```
- === "Result"
- [![Tabs]][Tabs]
+ === "Result"
+ [![Tabs]][tabs]
- [Tabs]: ../../assets/user_guides/components/tabs.png
+[tabs]: ../../assets/user_guides/components/tabs.png
diff --git a/vizro-core/docs/pages/user-guides/themes.md b/vizro-core/docs/pages/user-guides/themes.md
index 6f78441d5..ac1d6fc7b 100644
--- a/vizro-core/docs/pages/user-guides/themes.md
+++ b/vizro-core/docs/pages/user-guides/themes.md
@@ -1,15 +1,13 @@
# How to use themes
-This guide shows you how to use themes. Themes are pre-designed collections of stylings that are applied to entire charts and dashboards.
-The themes provided by Vizro are infused with our design best practices that make charts and dashboards look visually consistent and professional.
+This guide shows you how to use themes. Themes are pre-designed collections of stylings that are applied to entire charts and dashboards. The themes provided by Vizro are infused with our design best practices that make charts and dashboards look visually consistent and professional.
## Themes in dashboards
-The [`Dashboard`][vizro.models.Dashboard] model accepts an optional `theme` argument, where you can choose between
-a `vizro_dark` and a `vizro_light` theme. If not specified then `theme` defaults to `vizro_dark`. The theme is applied to the entire dashboard and its charts/components when a user first loads your dashboard. Regardless of the theme applied on first load, users can always switch between light and dark themes via the toggle button in the upper-right corner of the dashboard.
+
+The [`Dashboard`][vizro.models.Dashboard] model accepts an optional `theme` argument, where you can choose between a `vizro_dark` and a `vizro_light` theme. If not specified then `theme` defaults to `vizro_dark`. The theme is applied to the entire dashboard and its charts/components when a user first loads your dashboard. Regardless of the theme applied on first load, users can always switch between light and dark themes via the toggle button in the upper-right corner of the dashboard.
!!! example "Change theme"
=== "app.py"
-
```{.python pycafe-link hl_lines="18"}
import vizro.models as vm
import vizro.plotly.express as px
@@ -32,47 +30,40 @@ a `vizro_dark` and a `vizro_light` theme. If not specified then `theme` defaults
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml hl_lines="12"
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: scatter_matrix
- color: species
- data_frame: iris
- dimensions: ["sepal_length", "sepal_width", "petal_length", "petal_width"]
- type: graph
- title: Changing themes
+ - components:
+ - figure:
+ _target_: scatter_matrix
+ color: species
+ data_frame: iris
+ dimensions: [sepal_length, sepal_width, petal_length, petal_width]
+ type: graph
+ title: Changing themes
theme: vizro_light
```
+
=== "Result - vizro_light"
- [![Light]][Light]
+ [![Light]][light]
- [Light]: ../../assets/user_guides/themes/light.png
=== "Result - vizro_dark"
- [![Dark]][Dark]
-
- [Dark]: ../../assets/user_guides/themes/dark.png
-
+ [![Dark]][dark]
## Themes in plotly charts
You can also use our templates for plotly charts outside the dashboard. This is useful in a few contexts:
-* Creation of standalone charts to be used independently of a Vizro dashboard.
-* Rapid development of charts for eventual use in a Vizro dashboard, for example in a Jupyter Notebook.
+- Creation of standalone charts to be used independently of a Vizro dashboard.
+- Rapid development of charts for eventual use in a Vizro dashboard, for example in a Jupyter Notebook.
!!! note
+ Using `import vizro.plotly.express as px` is equal to using `import plotly.express as px`, but with the added benefit of being able to integrate the resulting chart code into a Vizro dashboard. Vizro offers a minimal layer on top of Plotly's existing charting library, allowing you to seamlessly use all the existing charts and functionalities provided by plotly.express without any modifications.
- Using `import vizro.plotly.express as px` is equivalent to using `import plotly.express as px`,
- but with the added benefit of being able to integrate the resulting chart code into a Vizro dashboard.
- Vizro offers a minimal layer on top of Plotly's existing charting library, allowing you to seamlessly use all the
- existing charts and functionalities provided by plotly.express without any modifications.
-
-Our `vizro_dark` and `vizro_light` themes are automatically registered to `plotly.io.templates` when importing Vizro.
-Consult the plotly documentation for [more details on how templates work in plotly](https://plotly.com/python/templates/#theming-and-templates).
+Our `vizro_dark` and `vizro_light` themes are automatically registered to `plotly.io.templates` when importing Vizro. Consult the plotly documentation for [more details on how templates work in plotly](https://plotly.com/python/templates/#theming-and-templates).
By default, plots imported from `vizro.plotly.express` have the `vizro_dark` theme applied. This can be altered either globally or for individual plots.
@@ -87,14 +78,20 @@ pio.templates.default = "vizro_light"
```
### Set themes for selected charts
+
To change the template for a selected chart only, use the `template` parameter and run:
```python
import vizro.plotly.express as px
df = px.data.iris()
-px.scatter_matrix(df,
- dimensions=["sepal_length", "sepal_width", "petal_length", "petal_width"],
- color="species",
- template="vizro_light")
+px.scatter_matrix(
+ df,
+ dimensions=["sepal_length", "sepal_width", "petal_length", "petal_width"],
+ color="species",
+ template="vizro_light",
+)
```
+
+[dark]: ../../assets/user_guides/themes/dark.png
+[light]: ../../assets/user_guides/themes/light.png
diff --git a/vizro-core/docs/pages/user-guides/visual-formatting.md b/vizro-core/docs/pages/user-guides/visual-formatting.md
index 7b384f3e9..56d1d2d52 100644
--- a/vizro-core/docs/pages/user-guides/visual-formatting.md
+++ b/vizro-core/docs/pages/user-guides/visual-formatting.md
@@ -1,17 +1,13 @@
# How to customize the style of Vizro dashboards
-Vizro has a default styling to help users with no design experience get started.
-There are several options if you want to customize the style:
+Vizro has a default styling to help users with no design experience get started. There are several options if you want to customize the style:
-* **[Configure the `Layout`](layouts.md)**: Customize the arrangement of your components inside your Vizro dashboard.
+- **[Configure the `Layout`](layouts.md)**: Customize the arrangement of your components inside your Vizro dashboard.
-* **[Apply a theme](themes.md)**: Choose between a dark or light theme.
+- **[Apply a theme](themes.md)**: Choose between a dark or light theme.
-* **[Manage assets](assets.md)**: Enhance your dashboard by adding images, scripts, and stylesheets to your assets folder.
+- **[Manage assets](assets.md)**: Enhance your dashboard by adding images, scripts, and stylesheets to your assets folder.
-* **[Customize CSS](custom-css.md)**: Incorporate custom CSS to deviate from the default styling and create a
-unique appearance for your Vizro dashboard.
+- **[Customize CSS](custom-css.md)**: Incorporate custom CSS to deviate from the default styling and create a unique appearance for your Vizro dashboard.
-* **[Customize your `component`](components.md)**: Change the appearance of components like the [Graph](graph.md), the
-[Table](table.md) and the [AgGrid](table.md), by passing extra arguments. Refer to the relevant user guide for
-more details.
+- **[Customize your `component`](components.md)**: Change the appearance of components like the [Graph](graph.md), the [Table](table.md) and the [AgGrid](table.md), by passing extra arguments. Refer to the relevant user guide for more details.
diff --git a/vizro-core/examples/README.md b/vizro-core/examples/README.md
index 72146bfb7..53cf932b7 100644
--- a/vizro-core/examples/README.md
+++ b/vizro-core/examples/README.md
@@ -4,8 +4,7 @@ Please note that this folder contains only example dashboards that are still **i
### Vizro examples gallery
-To view a comprehensive list of available demos, please visit our [examples gallery](http://vizro.mckinsey.com/).
-There, you can explore a wide range of dashboards and applications created with Vizro.
+To view a comprehensive list of available demos, please visit our [examples gallery](http://vizro.mckinsey.com/). There, you can explore a wide range of dashboards and applications created with Vizro.
diff --git a/vizro-core/examples/visual-vocabulary/README.md b/vizro-core/examples/visual-vocabulary/README.md
index 3b298520e..e59b3103c 100644
--- a/vizro-core/examples/visual-vocabulary/README.md
+++ b/vizro-core/examples/visual-vocabulary/README.md
@@ -2,14 +2,11 @@
### Welcome to our visual vocabulary dashboard! 🎨
-This dashboard serves as a comprehensive guide for selecting and creating various types of charts. It helps you decide
-when to use each chart type, and offers sample Python code using [Plotly](https://plotly.com/python/), and
-instructions for embedding these charts into a [Vizro](https://github.com/mckinsey/vizro) dashboard.
+This dashboard serves as a comprehensive guide for selecting and creating various types of charts. It helps you decide when to use each chart type, and offers sample Python code using [Plotly](https://plotly.com/python/), and instructions for embedding these charts into a [Vizro](https://github.com/mckinsey/vizro) dashboard.
The charts in this dashboard are designed to make it easy for anyone to create beautiful and sophisticated visuals.
-Our goal is to help you understand best practices in data visualization, ensure your charts effectively communicate
-your message, and streamline the creation of high-quality, interactive visualizations.
+Our goal is to help you understand best practices in data visualization, ensure your charts effectively communicate your message, and streamline the creation of high-quality, interactive visualizations.
Created by:
@@ -19,12 +16,9 @@ Created by:
Inspired by:
-- [The FT Visual Vocabulary](https://github.com/Financial-Times/chart-doctor/blob/main/visual-vocabulary/README.md):
- [Alan Smith](https://github.com/alansmithy), [Chris Campbell](https://github.com/digitalcampbell), Ian Bott,
- Liz Faunce, Graham Parrish, Billy Ehrenberg, Paul McCallum, [Martin Stabe](https://github.com/martinstabe).
+- [The FT Visual Vocabulary](https://github.com/Financial-Times/chart-doctor/blob/main/visual-vocabulary/README.md): [Alan Smith](https://github.com/alansmithy), [Chris Campbell](https://github.com/digitalcampbell), Ian Bott, Liz Faunce, Graham Parrish, Billy Ehrenberg, Paul McCallum, [Martin Stabe](https://github.com/martinstabe).
-- [The Graphic Continuum](https://www.informationisbeautifulawards.com/showcase/611-the-graphic-continuum):
- Jon Swabish and Severino Ribecca
+- [The Graphic Continuum](https://www.informationisbeautifulawards.com/showcase/611-the-graphic-continuum): Jon Swabish and Severino Ribecca
Credits and sources:
@@ -102,13 +96,12 @@ The dashboard is still in development. Below is an overview of the chart types f
Contributions are welcome! To contribute a chart, follow the steps below:
1. Check that a `svg` file named after the chart type is contained in the [assets](https://github.com/mckinsey/vizro/tree/main/vizro-core/examples/visual-vocabulary/assets/images/charts) folder. If not, [raise an issue](https://github.com/mckinsey/vizro/issues) in the repository.
-2. Add a `.py` file containing a code example of the chart type in the `pages/examples` folder, for instance, `area.py`. Take a look at existing examples.
-3. Create a new page for the chart type and add it to the relevant category `.py` file such as `correlation.py`,
- `deviation.py`, `distribution.py`, etc. Ensure you add the page to the list of `pages` at the end of the `.py` file.
-4. Remove the `IncompletePage(..)` entry for that chart type in `chart_groups.py`.
-5. Update this `README.md` with the new chart type, its status, category, and API links.
+1. Add a `.py` file containing a code example of the chart type in the `pages/examples` folder, for instance, `area.py`. Take a look at existing examples.
+1. Create a new page for the chart type and add it to the relevant category `.py` file such as `correlation.py`, `deviation.py`, `distribution.py`, etc. Ensure you add the page to the list of `pages` at the end of the `.py` file.
+1. Remove the `IncompletePage(..)` entry for that chart type in `chart_groups.py`.
+1. Update this `README.md` with the new chart type, its status, category, and API links.
## How to run the example locally
1. Run the example with the command `hatch run example visual-vocabulary`.
-2. You should now be able to access the app locally via http://127.0.0.1:8051/.
+1. You should now be able to access the app locally via http://127.0.0.1:8051/.
-
- #### Header level 4
- type: card
- - text: |
- Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
-
- Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
-
- Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
-
- Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
- title: Paragraphs
- type: card
- - text: |
- >
- > A block quote is a long quotation, indented to create a separate block of text.
- >
- title: Block Quotes
- type: card
- - text: |
- * Item A
- * Sub Item 1
- * Sub Item 2
- * Item B
- title: Lists
- type: card
- - text: |
- This word will be *italic*
-
- This word will be **bold**
-
- This word will be _**bold and italic**_
- title: Emphasis
- type: card
- title: Customizing Text
+ - components:
+ - text: |
+ # Header level 1
+
+ ## Header level 2
+
+ ### Header level 3
+
+ #### Header level 4
+ type: card
+ - text: |
+ Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
+
+ Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
+
+ Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
+
+ Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
+ title: Paragraphs
+ type: card
+ - text: |
+ >
+ > A block quote is a long quotation, indented to create a separate block of text.
+ >
+ title: Block Quotes
+ type: card
+ - text: |
+ * Item A
+ * Sub Item 1
+ * Sub Item 2
+ * Item B
+ title: Lists
+ type: card
+ - text: |
+ This word will be *italic*
+
+ This word will be **bold**
+
+ This word will be _**bold and italic**_
+ title: Emphasis
+ type: card
+ title: Customizing Text
```
- === "Result"
- [![CardText]][CardText]
- [CardText]: ../../assets/user_guides/components/card_text.png
+ === "Result"
+ [![CardText]][cardtext]
### Place an image on a card
@@ -189,11 +185,10 @@ Images can be added to the `text` parameter by using the standard markdown synta
``
-An image ALT text offers a description to your image and serves as a text placeholder or to improve the
-accessibility of your app. Providing an image ALT text is optional.
+An image ALT text offers a description to your image and serves as a text placeholder or to improve the accessibility of your app. Providing an image ALT text is optional.
1. To use a relative Image URL, place an image of your choice into your `assets` folder first
-2. Use markdown to render your image by using one of the following syntax:
+1. Use markdown to render your image by using one of the following syntax:
- Relative Image URL: ``
- Absolute Image URL: ``
@@ -228,55 +223,50 @@ accessibility of your app. Providing an image ALT text is optional.
Run and edit this code in PyCafe
-
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - text: |
- 
+ - components:
+ - text: |
+ 
- Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
+ Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
- Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
+ Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
- Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
- title: My card with image!
- type: card
- title: Placing Images
+ Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
+ title: My card with image!
+ type: card
+ title: Placing Images
```
- === "Result"
- [![CardImageDefault]][CardImageDefault]
- [CardImageDefault]: ../../assets/user_guides/components/card_image_default.png
+ === "Result"
+ [![CardImageDefault]][cardimagedefault]
!!! note
-
- Note that inserting images using html is by default turned off by the `dcc.Markdown` to prevent users being exposed
- to cross-site scripting attacks. If you need to turn it on, a custom component would have to be created.
+ Note that inserting images using HTML is by default turned off by the `dcc.Markdown` to prevent users being exposed to cross-site scripting attacks. If you need to turn it on, a custom component would have to be created.
You might notice that the image is quite large. You'll find out how to style images in terms of their position and size in the next section.
-
### Style a card image
To change the size or position of the image, add a URL hash to your image like this:
``
-Note the added URL hash `#my-image`. Now create a CSS file placed in your `assets` folder
-and give an attribute selector to select images with that matching URL hash.
+Note the added URL hash `#my-image`. Now create a CSS file placed in your `assets` folder and give an attribute selector to select images with that matching URL hash.
!!! example "Card with styled image"
=== "images.css"
- ```css
- img[src*="#my-image"] {
- width: 120px;
- height: 120px;
- }
- ```
+ ```css
+ img[src*="#my-image"] {
+ width: 120px;
+ height: 120px;
+ }
+ ```
+
=== "app.py"
```py
import vizro.models as vm
@@ -313,23 +303,22 @@ and give an attribute selector to select images with that matching URL hash.
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - text: |
- 
+ - components:
+ - text: |
+ 
- Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
+ Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
- Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
+ Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
- Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
- title: My card with image!
- type: card
- title: Styling Images
+ Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
+ title: My card with image!
+ type: card
+ title: Styling Images
```
- === "Result"
- [![CardImageStyled]][CardImageStyled]
- [CardImageStyled]: ../../assets/user_guides/components/card_image_styled.png
+ === "Result"
+ [![CardImageStyled]][cardimagestyled]
Use the following pre-defined URL hashes in your image path to apply Vizro's default styling.
@@ -341,12 +330,13 @@ Use the following pre-defined URL hashes in your image path to apply Vizro's def
!!! example "Card with floating image"
=== "images.css"
- ```css
- img[src*="#my-image"] {
- width: 120px;
- height: 120px;
- }
- ```
+ ```css
+ img[src*="#my-image"] {
+ width: 120px;
+ height: 120px;
+ }
+ ```
+
=== "app.py"
```py
import vizro.models as vm
@@ -389,29 +379,28 @@ Use the following pre-defined URL hashes in your image path to apply Vizro's def
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - text: |
- 
+ - components:
+ - text: |
+ 
- Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
+ Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
- Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
+ Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
- Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
+ Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
- Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
+ Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
- Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
+ Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
- Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
- title: My card with floating image!
- type: card
- title: Floating Images
+ Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
+ title: My card with floating image!
+ type: card
+ title: Floating Images
```
- === "Result"
- [![CardImageFloating]][CardImageFloating]
- [CardImageFloating]: ../../assets/user_guides/components/card_image_floating.png
+ === "Result"
+ [![CardImageFloating]][cardimagefloating]
#### Card with icon
@@ -442,38 +431,34 @@ Use the following pre-defined URL hashes in your image path to apply Vizro's def
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - text: |
- 
+ - components:
+ - text: |
+ 
- ### Card Title
+ ### Card Title
- Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut fringilla dictum lacus eget fringilla.
- Maecenas in various nibh, quis venenatis nulla. Integer et libero ultrices, scelerisque velit sed.
- type: card
- title: Card with icon
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut fringilla dictum lacus eget fringilla.
+ Maecenas in various nibh, quis venenatis nulla. Integer et libero ultrices, scelerisque velit sed.
+ type: card
+ title: Card with icon
```
- === "Result"
- [![CardIcon]][CardIcon]
-
- [CardIcon]: ../../assets/user_guides/components/card_icon.png
+ === "Result"
+ [![CardIcon]][cardicon]
### Make an icon responsive to theme switch
-To make an icon responsive to the theme switch, override the value of the [`filter` CSS property](https://developer.mozilla.org/en-US/docs/Web/CSS/filter).
-The `filter` CSS property lets you add visual effects to elements using different functions. In our example, we're using the `--inverse-color` CSS variable from the Vizro theme.
-It uses the CSS `invert()` function to flip the color of the icon when you switch themes. Note that this only works if your initial icon has a white fill color. If your icon is not white, you can change its color by adding `fill="white"` to the SVG code.
-Assign the predefined CSS variable `--inverse-color` to the `filter` property of your selected icon.
+To make an icon responsive to the theme switch, override the value of the [`filter` CSS property](https://developer.mozilla.org/en-US/docs/Web/CSS/filter). The `filter` CSS property lets you add visual effects to elements using different functions. In our example, we're using the `--inverse-color` CSS variable from the Vizro theme. It uses the CSS `invert()` function to flip the color of the icon when you switch themes. Note that this only works if your initial icon has a white fill color. If your icon is not white, you can change its color by adding `fill="white"` to the SVG code. Assign the predefined CSS variable `--inverse-color` to the `filter` property of your selected icon.
```css
img[src*="#my-image"] {
- filter: var(--inverse-color);
+ filter: var(--inverse-color);
}
```
@@ -482,18 +467,15 @@ img[src*="#my-image"] {
### Create a navigation card
-This section describes how to use the [`Card`][vizro.models.Card] component to create a navigation card,
-enabling users to navigate to another page by clicking on the card area.
+This section describes how to use the [`Card`][vizro.models.Card] component to create a navigation card, enabling users to navigate to another page by clicking on the card area.
-For a button-style link navigation component, see the [separate guide on creating a link button](#create-a-link-button).
-To configure the navigation panel on the left hand side of the screen, refer to the
-[separate guide on navigation](navigation.md).
+For a button-style link navigation component, see the [separate guide on creating a link button](#create-a-link-button). To configure the navigation panel on the left hand side of the screen, refer to the [separate guide on navigation](navigation.md).
To create a navigation card:
1. Insert the [`Card`][vizro.models.Card] into the `components` argument of the [`Page`][vizro.models.Page].
-2. Pass your markdown text to the `Card.text`.
-3. Pass a relative or absolute URL to the `Card.href`.
+1. Pass your markdown text to the `Card.text`.
+1. Pass a relative or absolute URL to the `Card.href`.
!!! example "Navigation Card"
=== "app.py"
@@ -537,72 +519,65 @@ To create a navigation card:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - text: |
- ### Filters and parameters
-
- Leads to the first page on click
- href: /filters-and-parameters
- type: card
- - text: |
- ### Google - External Link
-
- Leads to an external link on click.
- href: https://google.com
- type: card
- title: Homepage
- - components:
- - figure:
- _target_: scatter
- color: sepal_width
- data_frame: iris
- x: sepal_length
- y: petal_width
- type: graph
- title: Filters and parameters
+ - components:
+ - text: |
+ ### Filters and parameters
+
+ Leads to the first page on click
+ href: /filters-and-parameters
+ type: card
+ - text: |
+ ### Google - External Link
+
+ Leads to an external link on click.
+ href: https://google.com
+ type: card
+ title: Homepage
+ - components:
+ - figure:
+ _target_: scatter
+ color: sepal_width
+ data_frame: iris
+ x: sepal_length
+ y: petal_width
+ type: graph
+ title: Filters and parameters
```
- === "Result"
- [![NavCard]][NavCard]
- [NavCard]: ../../assets/user_guides/components/nav_card.png
+ === "Result"
+ [![NavCard]][navcard]
If you now click on the card area, you should automatically be redirected to the relevant `href`.
!!! note
-
When using the [`Card`][vizro.models.Card], keep the following in mind:
- If the href given is a relative URL, it should match the `path` of the [`Page`][vizro.models.Page] that the [`Card`][vizro.models.Card] should navigate to.
- If the href given is an absolute link, it should start with `https://` or an equivalent protocol.
-
### Create a KPI card
-To create a KPI card, you can use the existing KPI card functions from [`vizro.figures`](../API-reference/figure-callables.md).
-Unlike the static text card `vm.Card`, a KPI card must be created using a figure function,
-which enables the text content of the KPI to change based on input from controls or actions.
+
+To create a KPI card, you can use the existing KPI card functions from [`vizro.figures`](../API-reference/figure-callables.md). Unlike the static text card `vm.Card`, a KPI card must be created using a figure function, which enables the text content of the KPI to change based on input from controls or actions.
For detailed examples on how to create a KPI card, refer to the [figure user guide on KPI cards](figure.md#key-performance-indicator-kpi-cards).
## Buttons
-The Button component is commonly used for interactive dashboard interactions
-such as form submissions, navigation links, and other action triggers.
-
-To add a [`Button`][vizro.models.Button], insert it into the `components` argument of the
-[`Page`][vizro.models.Page].
+The Button component is commonly used for interactive dashboard interactions such as form submissions, navigation links, and other action triggers.
+To add a [`Button`][vizro.models.Button], insert it into the `components` argument of the [`Page`][vizro.models.Page].
### Customize button text
You can configure the `text` argument to alter the display text of the [`Button`][vizro.models.Button].
!!! example "Customize text"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -616,26 +591,24 @@ You can configure the `text` argument to alter the display text of the [`Button`
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- components:
- - type: button
- text: I'm a button!
+ - type: button
+ text: I'm a button!
title: Button with text
```
- === "Result"
- [![ButtonText]][ButtonText]
-
- [ButtonText]: ../../assets/user_guides/components/button_text.png
+ === "Result"
+ [![ButtonText]][buttontext]
### Create a link button
-To navigate to a different page using a button with an anchor tag, assign an absolute or relative URL to the
-`Button.href`.
+To navigate to a different page using a button with an anchor tag, assign an absolute or relative URL to the `Button.href`.
```python
import vizro.models as vm
@@ -645,16 +618,11 @@ vm.Button(text="Leave us a star! ⭐", href="https://github.com/mckinsey/vizro")
### Attach an action
-You can use the [`Button`][vizro.models.Button] to trigger predefined action functions, such as exporting data.
-To explore the available options for [`Actions`][vizro.models.Action], refer to our [API reference][vizro.actions].
-Use the `Button.actions` argument to specify which action function executes when the button is clicked.
-
-The example below demonstrates how to configure a button to export the filtered data of a target chart using the
-[export_data][vizro.actions.export_data] action function.
+You can use the [`Button`][vizro.models.Button] to trigger predefined action functions, such as exporting data. To explore the available options for [`Actions`][vizro.models.Action], refer to our [API reference][vizro.actions]. Use the `Button.actions` argument to specify which action function executes when the button is clicked.
+The example below demonstrates how to configure a button to export the filtered data of a target chart using the [export_data][vizro.actions.export_data] action function.
!!! example "Button with action"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -690,29 +658,30 @@ The example below demonstrates how to configure a button to export the filtered
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- components:
- - figure:
- _target_: scatter
- x: sepal_width
- y: sepal_length
- color: species
- size: petal_length
- data_frame: iris
- id: scatter_chart
- type: graph
- - type: button
- text: Export data
- id: export_data
- actions:
- - function:
- _target_: export_data
- targets:
- - scatter_chart
+ - figure:
+ _target_: scatter
+ x: sepal_width
+ y: sepal_length
+ color: species
+ size: petal_length
+ data_frame: iris
+ id: scatter_chart
+ type: graph
+ - type: button
+ text: Export data
+ id: export_data
+ actions:
+ - function:
+ _target_: export_data
+ targets:
+ - scatter_chart
controls:
- column: species
selector:
@@ -728,14 +697,13 @@ The example below demonstrates how to configure a button to export the filtered
- [1]
title: My first page
```
- === "Result"
- [![Button]][Button]
- [Button]: ../../assets/user_guides/components/button.png
+ === "Result"
+ [![Button]][button]
### Use as a control
-The [`Button`][vizro.models.Button] component is currently reserved to be used inside the main panel (right-side) of the dashboard.
-However, there might be use cases where one would like to place the `Button` inside the control panel (left-side) with the other controls.
+
+The [`Button`][vizro.models.Button] component is currently reserved to be used inside the main panel (right-side) of the dashboard. However, there might be use cases where one would like to place the `Button` inside the control panel (left-side) with the other controls.
In this case, follow the user-guide outlined for [creating custom components](custom-components.md) and manually add the `Button` as a valid type to the `controls` argument by running the following lines before your dashboard configurations:
@@ -748,3 +716,13 @@ vm.Page.add_type("controls", vm.Button)
# Add dashboard configurations below
...
```
+
+[button]: ../../assets/user_guides/components/button.png
+[buttontext]: ../../assets/user_guides/components/button_text.png
+[card]: ../../assets/user_guides/components/card.png
+[cardicon]: ../../assets/user_guides/components/card_icon.png
+[cardimagedefault]: ../../assets/user_guides/components/card_image_default.png
+[cardimagefloating]: ../../assets/user_guides/components/card_image_floating.png
+[cardimagestyled]: ../../assets/user_guides/components/card_image_styled.png
+[cardtext]: ../../assets/user_guides/components/card_text.png
+[navcard]: ../../assets/user_guides/components/nav_card.png
diff --git a/vizro-core/docs/pages/user-guides/components.md b/vizro-core/docs/pages/user-guides/components.md
index 106bf6a0b..45ea5a123 100755
--- a/vizro-core/docs/pages/user-guides/components.md
+++ b/vizro-core/docs/pages/user-guides/components.md
@@ -1,8 +1,6 @@
# Components
-The [`Page`][vizro.models.Page] model accepts the `components` argument, where you can enter any of the components
-listed below to fill your dashboard with visuals.
-
+The [`Page`][vizro.models.Page] model accepts the `components` argument, where you can enter any of the components listed below to fill your dashboard with visuals.
@@ -38,7 +36,6 @@ listed below to fill your dashboard with visuals.
[:octicons-arrow-right-24: View user guide](card-button.md)
-
- :octicons-table-16:{ .lg .middle } __Containers__
---
diff --git a/vizro-core/docs/pages/user-guides/container.md b/vizro-core/docs/pages/user-guides/container.md
index c7e327c5f..2f379709e 100755
--- a/vizro-core/docs/pages/user-guides/container.md
+++ b/vizro-core/docs/pages/user-guides/container.md
@@ -2,30 +2,22 @@
This guide shows you how to use containers to group your components into sections and subsections within the page.
-A [`Container`][vizro.models.Container] complements the idea of a [`Page`][vizro.models.Page], and the two models have almost identical arguments.
- [`Page.layout`](layouts.md) offers a way to structure the overall layout of the page, and a `Container` enables more granular control within a specific section of that page.
+A [`Container`][vizro.models.Container] complements the idea of a [`Page`][vizro.models.Page], and the two models have almost identical arguments. [`Page.layout`](layouts.md) offers a way to structure the overall layout of the page, and a `Container` enables more granular control within a specific section of that page.
-While there is currently no clear difference in rendering, extra functionality will be added to the `Container` soon (including controls specific to that container),
-enhancing the ability to manage related components.
+While there is currently no clear difference in rendering, extra functionality will be added to the `Container` soon (including controls specific to that container), enhancing the ability to manage related components.
!!! note "Displaying multiple containers inside Tabs"
-
An alternative way to display multiple containers on one page is to place them inside [Tabs](tabs.md).
- [`Tabs`][vizro.models.Tabs] organize and separate groups of related content in a dashboard, letting users switch between different sections or views.
- They are a way of putting multiple containers into the same screen space, and letting the user switch between them.
+ [`Tabs`][vizro.models.Tabs] organize and separate groups of related content in a dashboard, letting users switch between different sections or views. They are a way of putting multiple containers into the same screen space, and letting the user switch between them.
{ width="500" }
-
-
## When to use containers
-In general, any arbitrarily granular layout can already be achieved by [using `Page.layout`](layouts.md) alone and is our
-recommended approach if you want to arrange components on a page with consistent row and/or column spacing.
-`Page.layout` has a `grid` argument that sets the overall layout of the page.
-`Container.layout` also has a `grid` argument. This enables you to insert a further `grid` into a component's space on the page,
-enabling more granular control by breaking the overall page grid into subgrids.
+In general, any arbitrarily granular layout can already be achieved by [using `Page.layout`](layouts.md) alone and is our recommended approach if you want to arrange components on a page with consistent row and/or column spacing.
+
+`Page.layout` has a `grid` argument that sets the overall layout of the page. `Container.layout` also has a `grid` argument. This enables you to insert a further `grid` into a component's space on the page, enabling more granular control by breaking the overall page grid into subgrids.
Here are a few cases where you might want to use a `Container` instead of `Page.layout`:
@@ -34,14 +26,14 @@ Here are a few cases where you might want to use a `Container` instead of `Page.
- If you want different row and column spacing between subgrids
- If you want to apply controls to selected subgrids (will be supported soon)
-
## Basic containers
+
To add a [`Container`][vizro.models.Container] to your page, do the following:
1. Insert the `Container` into the `components` argument of the [`Page`][vizro.models.Page]
-2. Set a `title` for your `Container`
-3. Configure your `components`, [read the overview page for various options](components.md)
-4. (optional) Configure your `layout`, see [the guide on `Layout`](layouts.md)
+1. Set a `title` for your `Container`
+1. Configure your `components`, [read the overview page for various options](components.md)
+1. (optional) Configure your `layout`, see [the guide on `Layout`](layouts.md)
!!! example "Container"
=== "app.py"
@@ -105,7 +97,7 @@ To add a [`Container`][vizro.models.Container] to your page, do the following:
```
1. Note that the `Page.layout` argument is not specified here and will therefore defaults to `[[0], [1]]`, meaning the containers will be **vertically stacked** down the page in one column.
- 2. **Horizontally stack** the components side-by-side inside this `Container` in one row.
+ 1. **Horizontally stack** the components side-by-side inside this `Container` in one row.
=== "app.yaml"
```yaml
@@ -149,27 +141,20 @@ To add a [`Container`][vizro.models.Container] to your page, do the following:
title: Container II
title: Containers
```
- === "Result"
- [![Container]][Container]
- [Container]: ../../assets/user_guides/components/containers.png
+ === "Result"
+ [![Container]][container]
Note that an almost identical layout can also be achieved using solely the [`Page.layout`](layouts.md) by configuring the `Page.layout` as `vm.Layout(grid = [[0, 1], [2, 2]])`.
## Nested containers
-Containers can be nested, providing a hierarchical structure for organizing components.
-This nesting capability enables users to create more complex layouts and manage related components at any level of granularity.
+
+Containers can be nested, providing a hierarchical structure for organizing components. This nesting capability enables users to create more complex layouts and manage related components at any level of granularity.
To create nested containers, add a `Container` to the `components` argument of another `Container`.
```python title="Example"
-vm.Container(
- title="Parent Container",
- components=[
- vm.Container(
- title="Child Container",
- components=[vm.Button()]
- )
- ]
-)
+vm.Container(title="Parent Container", components=[vm.Container(title="Child Container", components=[vm.Button()])])
```
+
+[container]: ../../assets/user_guides/components/containers.png
diff --git a/vizro-core/docs/pages/user-guides/custom-actions.md b/vizro-core/docs/pages/user-guides/custom-actions.md
index e5fa3afd8..2fb66cd2c 100644
--- a/vizro-core/docs/pages/user-guides/custom-actions.md
+++ b/vizro-core/docs/pages/user-guides/custom-actions.md
@@ -1,17 +1,16 @@
# How to create custom actions
-This guide demonstrates the usage of custom actions, an idea that shares similarities with, but is not identical to [callbacks](https://dash.plotly.com/basic-callbacks) in `Dash`.
-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.
+This guide demonstrates the usage of custom actions, an idea that shares similarities with, but is not identical to [callbacks](https://dash.plotly.com/basic-callbacks) in `Dash`. 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.
+
## Simple custom action
Custom actions enable you to implement your own action function. Simply do the following:
1. define a function
-2. decorate it with the `@capture("action")` decorator
-3. add it as a `function` argument inside the [`Action`][vizro.models.Action] model
+1. decorate it with the `@capture("action")` decorator
+1. add it as a `function` argument inside the [`Action`][vizro.models.Action] model
The following example shows how to create a custom action that postpones execution of the next action in the chain for `t` seconds.
@@ -58,27 +57,24 @@ The following example shows how to create a custom action that postpones executi
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
- ```yaml
- # Custom actions are currently only possible via Python configuration
- ```
-
+ Custom actions are currently only possible via Python configuration.
+
## Interact with inputs and outputs
+
When a custom action needs to interact with the dashboard, it is possible to define `inputs` and `outputs` for the custom action.
-- `inputs` represents dashboard component properties whose values are passed to the custom action function as arguments.
-It is a list of strings in the format `"."` (for example, `"my_selector.value`").
-- `outputs` represents dashboard component properties corresponding to the custom action function return value(s).
-Similar to `inputs`, it is a list of strings in the format `"."` (for example, `"my_card.children"`).
+- `inputs` represents dashboard component properties whose values are passed to the custom action function as arguments. It is a list of strings in the format `"."` (for example, `"my_selector.value`").
+- `outputs` represents dashboard component properties corresponding to the custom action function return value(s). Similar to `inputs`, it is a list of strings in the format `"."` (for example, `"my_card.children"`).
### Example of `value` as input
-The following example shows a custom action that takes the `value` of the `vm.RadioItem` and returns it inside a
-[`Card`][vizro.models.Card] component.
-!!! example "Display `value` in Card"
+The following example shows a custom action that takes the `value` of the `vm.RadioItem` and returns it inside a [`Card`][vizro.models.Card] component.
+!!! example "Display `value` in Card"
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -113,23 +109,18 @@ The following example shows a custom action that takes the `value` of the `vm.Ra
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
- === "app.yaml"
- ```yaml
- # Custom actions are currently only possible via Python configuration
- ```
- === "Result"
- [![ValueAction]][ValueAction]
- [ValueAction]: ../../assets/user_guides/custom_actions/value_as_input.png
+ === "app.yaml"
+ Custom actions are currently only possible via Python configuration.
+ === "Result"
+ [![ValueAction]][valueaction]
### Example of `clickData` as input
-The following example shows how to create a custom action that shows the `clickData` of a chart in a
-[`Card`][vizro.models.Card] component. For further information on the structure and content of the `clickData`
-property, refer to the Dash documentation on [interactive visualizations](https://dash.plotly.com/interactive-graphing).
-!!! example "Display `clickData` in Card"
+The following example shows how to create a custom action that shows the `clickData` of a chart in a [`Card`][vizro.models.Card] component. For further information on the structure and content of the `clickData` property, refer to the Dash documentation on [interactive visualizations](https://dash.plotly.com/interactive-graphing).
+!!! example "Display `clickData` in Card"
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -173,21 +164,18 @@ property, refer to the Dash documentation on [interactive visualizations](https:
```
1. Just as for any Python function, the names of the arguments `show_species` and `points_data` are arbitrary and do not need to match on to the names of `inputs` in any particular way.
- 2. We _bind_ (set) the argument `show_species` to the value `True` in the initial specification of the `function` field. These are static values that are fixed when the dashboard is _built_.
- 3. The content of `inputs` will "fill in the gaps" by setting values for the remaining unbound arguments in `my_custom_action`. Here there is one such argument, named `points_data`. Values for these are bound _dynamically at runtime_ to reflect the live state of your dashboard.
+ 1. We _bind_ (set) the argument `show_species` to the value `True` in the initial specification of the `function` field. These are static values that are fixed when the dashboard is _built_.
+ 1. The content of `inputs` will "fill in the gaps" by setting values for the remaining unbound arguments in `my_custom_action`. Here there is one such argument, named `points_data`. Values for these are bound _dynamically at runtime_ to reflect the live state of your dashboard.
+
=== "app.yaml"
- ```yaml
- # Custom actions are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomAction]][CustomAction]
+ Custom actions are currently only possible via Python configuration.
- [CustomAction]: ../../assets/user_guides/custom_actions/clickdata_as_input.png
+ === "Result"
+ [![CustomAction]][customaction]
## Multiple return values
-The return value of the custom action function is propagated to the dashboard components that are defined in the `outputs` argument of the [`Action`][vizro.models.Action] model.
-If there is a single `output` defined then the function return value is directly assigned to the component property.
-If there are multiple `outputs` defined then the return value is iterated through and each part is assigned to each component property given in `outputs` in turn. This behavior is identical to Python's flexibility in managing multiple return values.
+
+The return value of the custom action function is propagated to the dashboard components that are defined in the `outputs` argument of the [`Action`][vizro.models.Action] model. If there is a single `output` defined then the function return value is directly assigned to the component property. If there are multiple `outputs` defined then the return value is iterated through and each part is assigned to each component property given in `outputs` in turn. This behavior is identical to Python's flexibility in managing multiple return values.
!!! example "Multiple return values"
=== "app.py"
@@ -246,17 +234,17 @@ If there are multiple `outputs` defined then the return value is iterated throug
```
1. `my_custom_action` returns two values (which will be in Python tuple).
- 2. These values are assigned to the `outputs` in the same order.
- === "app.yaml"
- ```yaml
- # Custom actions are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomAction2]][CustomAction2]
+ 1. These values are assigned to the `outputs` in the same order.
- [CustomAction2]: ../../assets/user_guides/custom_actions/custom_action_multiple_return_values.png
+ === "app.yaml"
+ Custom actions are currently only possible via Python configuration.
+ === "Result"
+ [![CustomAction2]][customaction2]
!!! warning
+ Note that users of this package are responsible for the content of any custom action function that they write. Take care to avoid leaking any sensitive information or exposing to any security threat during implementation. You should always [treat the content of user input as untrusted](https://community.plotly.com/t/writing-secure-dash-apps-community-thread/54619).
- Note that users of this package are responsible for the content of any custom action function that they write - especially with regard to leaking any sensitive information or exposing to any security threat during implementation. You should always [treat the content of user input as untrusted](https://community.plotly.com/t/writing-secure-dash-apps-community-thread/54619).
+[customaction]: ../../assets/user_guides/custom_actions/clickdata_as_input.png
+[customaction2]: ../../assets/user_guides/custom_actions/custom_action_multiple_return_values.png
+[valueaction]: ../../assets/user_guides/custom_actions/value_as_input.png
diff --git a/vizro-core/docs/pages/user-guides/custom-charts.md b/vizro-core/docs/pages/user-guides/custom-charts.md
index cb26614c8..1b77d0869 100644
--- a/vizro-core/docs/pages/user-guides/custom-charts.md
+++ b/vizro-core/docs/pages/user-guides/custom-charts.md
@@ -1,9 +1,9 @@
# 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 graphs](graph.md).
+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 graphs](graph.md).
## When to use a custom chart
+
In general, you should use the custom chart decorator `@capture("graph")` if your plotly chart needs any post-update calls or customization. For example:
- You want to use any of the post figure update calls by `plotly` such as `update_layout`, `update_xaxes`, `update_traces` (for more details, see the docs on [plotly's update calls](https://plotly.com/python/creating-and-updating-figures/#other-update-methods))
@@ -12,11 +12,10 @@ In general, you should use the custom chart decorator `@capture("graph")` if you
## Steps to create a custom chart
1. Define a function that returns a `go.Figure()`.
-2. Decorate it with `@capture("graph")`.
-3. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
-4. The visualization should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments
-will not react to dashboard controls such as [`Filter`](filters.md).
-5. Pass your function to the `figure` argument of the [`Graph`][vizro.models.Graph] model.
+1. Decorate it with `@capture("graph")`.
+1. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
+1. The visualization should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments will not react to dashboard controls such as [`Filter`](filters.md).
+1. Pass your function to the `figure` argument of the [`Graph`][vizro.models.Graph] model.
The minimal example below can be used as a base to build more sophisticated charts.
@@ -39,12 +38,10 @@ To alter the data in the `data_frame` argument, consider using a [Filter](filter
## Enhanced `plotly.express` chart with reference line
-The below examples shows a case where we enhance an existing `plotly.express` chart. We add a new argument (`hline`), that is used to draw a grey reference line at the height determined by the value of `hline`. The important thing to note is that we then
-add a `Parameter` that enables the dashboard user to interact with the argument, and hence move the line in this case. See the `Result` tab for an animation.
+The below examples shows a case where we enhance an existing `plotly.express` chart. We add a new argument (`hline`), that is used to draw a grey reference line at the height determined by the value of `hline`. The important thing to note is that we then add a `Parameter` that enables the dashboard user to interact with the argument, and hence move the line in this case. See the `Result` tab for an animation.
!!! example "Custom `plotly.express` scatter chart with a `Parameter`"
=== "app.py"
-
```{.python pycafe-link}
import vizro.models as vm
import vizro.plotly.express as px
@@ -86,17 +83,14 @@ add a `Parameter` that enables the dashboard user to interact with the argument,
Vizro().build(dashboard).run()
```
- 1. Note that arguments of the custom chart can be parametrized. Here we choose to parametrize the `hline` argument (see below).
- 2. Here we parametrize the `hline` argument, but any other argument can be parametrized as well. Since there is complete flexibility regarding what can be derived from such arguments, the dashboard user has a wide range of customization options.
- === "app.yaml"
- ```yaml
- # Custom charts are currently only possible via Python configuration
- ```
- === "Result"
- [![Graph2]][Graph2]
+ 1. Note that arguments of the custom chart can be parametrized. Here we choose to parametrize the `hline` argument (see below).
+ 1. Here we parametrize the `hline` argument, but any other argument can be parametrized as well. Since there is complete flexibility regarding what can be derived from such arguments, the dashboard user has a wide range of customization options.
- [Graph2]: ../../assets/user_guides/custom_charts/custom_chart_showcase_parameter.gif
+ === "app.yaml"
+ Custom charts are currently only possible via Python configuration.
+ === "Result"
+ [![Graph2]][graph2]
## New Waterfall chart based on `go.Figure()`
@@ -104,7 +98,6 @@ The below examples shows a more involved use-case. We create and style a waterfa
!!! example "Custom `go.Figure()` waterfall chart with a `Parameter`"
=== "app.py"
-
```{.python pycafe-link}
import pandas as pd
import plotly.graph_objects as go
@@ -162,10 +155,10 @@ The below examples shows a more involved use-case. We create and style a waterfa
```
=== "app.yaml"
- ```yaml
- # Custom charts are currently only possible via Python configuration
- ```
+ Custom charts are currently only possible via Python configuration.
+
=== "Result"
- [![Graph3]][Graph3]
+ [![Graph3]][graph3]
- [Graph3]: ../../assets/user_guides/custom_charts/custom_chart_waterfall.png
+[graph2]: ../../assets/user_guides/custom_charts/custom_chart_showcase_parameter.gif
+[graph3]: ../../assets/user_guides/custom_charts/custom_chart_waterfall.png
diff --git a/vizro-core/docs/pages/user-guides/custom-css.md b/vizro-core/docs/pages/user-guides/custom-css.md
index dd2d22275..d5bc5f7dc 100755
--- a/vizro-core/docs/pages/user-guides/custom-css.md
+++ b/vizro-core/docs/pages/user-guides/custom-css.md
@@ -1,25 +1,20 @@
# Customizing Vizro dashboard CSS
-Vizro is opinionated about visual formatting, and some elements, such as the layout of the navigation and controls,
-are fixed. You can customize some settings such as background colors, fonts, and other styles via CSS overrides.
+Vizro is opinionated about visual formatting, and some elements, such as the layout of the navigation and controls, are fixed. You can customize some settings such as background colors, fonts, and other styles via CSS overrides.
To make customizations, you need to:
1. **Add a CSS file to your `assets` folder**. Refer to our user guide on [adding static assets](assets.md#how-to-add-static-assets).
-2. **Identify the correct CSS selector** for the component you want to style.
-3. **Change the relevant CSS properties** in your CSS file.
-
-
+1. **Identify the correct CSS selector** for the component you want to style.
+1. **Change the relevant CSS properties** in your CSS file.
## Introduction to Vizro CSS
+
For a short introduction to CSS, we recommend reading this article: [Get Started with CSS in 5 Minutes](https://www.freecodecamp.org/news/get-started-with-css-in-5-minutes-e0804813fc3e/).
-For a more comprehensive tutorial, refer to the [W3Schools CSS tutorial](https://www.w3schools.com/css/default.asp).
-The entire tutorial is beneficial, but the section on [CSS selectors](https://www.w3schools.com/css/css_selectors.asp)
-will be particularly useful.
+For a more comprehensive tutorial, refer to the [W3Schools CSS tutorial](https://www.w3schools.com/css/default.asp). The entire tutorial is beneficial, but the section on [CSS selectors](https://www.w3schools.com/css/css_selectors.asp) will be particularly useful.
-In Vizro, the CSS file is read in as an external stylesheet. The most common way of applying any styling to
-Vizro is therefore through the use of CSS selectors:
+In Vizro, the CSS file is read in as an external stylesheet. The most common way of applying any styling to Vizro is therefore through the use of CSS selectors:
- **Element Selector**: Applies the style to all elements inside the Vizro app.
@@ -33,8 +28,7 @@ Vizro is therefore through the use of CSS selectors:
}
```
-- **Class selector:** Targets all elements with the given class for styling. All CSS classes must be preceded with a
-`.` symbol.
+- **Class selector:** Targets all elements with the given class for styling. All CSS classes must be preceded with a `.` symbol.
```
.card {
@@ -50,30 +44,25 @@ Vizro is therefore through the use of CSS selectors:
}
```
-
## Identify the correct CSS selector
Use Chrome DevTools or a similar tool (Web Inspector, Web Developer Tools, etc.) to inspect the HTML document in your browser.
-1. **Open DevTools:** In Google Chrome, right-click on the app and select "Inspect" from the context menu. This opens the
-HTML document of your Vizro app.
+1. **Open DevTools:** In Google Chrome, right-click on the app and select "Inspect" from the context menu. This opens the HTML document of your Vizro app.
-
-2. **Select an element:** Suppose you want to change the background color of your cards. Click the
-"Select an element in the page to inspect it" icon in the top left corner of the inspect panel.
+1. **Select an element:** Suppose you want to change the background color of your cards. Click the "Select an element in the page to inspect it" icon in the top left corner of the inspect panel.
-3. **Find the HTML Block:** Hover over the component you want to style. The corresponding HTML block will be
-highlighted in the HTML document.
+1. **Find the HTML Block:** Hover over the component you want to style. The corresponding HTML block will be highlighted in the HTML document.
Notice that the selected HTML block corresponds to the container of the card and has a CSS class, here it is `card`.
-4. **Apply CSS:** Use this CSS class to style the card component. In your CSS file, you can write:
+1. **Apply CSS:** Use this CSS class to style the card component. In your CSS file, you can write:
```
.card {
@@ -83,25 +72,25 @@ highlighted in the HTML document.
This changes the background color for any HTML element with the `card` class.
-**Tip:** You can also test your CSS live by editing the CSS attributes in the "Elements" panel.
-For example, temporarily add `background: blue;`. Note that this change will be lost upon reloading the page.
+**Tip:** You can also test your CSS live by editing the CSS attributes in the "Elements" panel. For example, temporarily add `background: blue;`. Note that this change will be lost upon reloading the page.
-
## CSS overwrites
### Overwrite CSS globally
-To overwrite any global CSS property, you need to target the element selector and place your CSS file with the
-overwrites in the `assets` folder.
+
+To overwrite any global CSS property, you need to target the element selector and place your CSS file with the overwrites in the `assets` folder.
!!! example "Overwrite CSS globally"
=== "my_css_file.css"
- ```css
- h1, h2 {
- color: hotpink;
- }
- ```
+ ```css
+ h1,
+ h2 {
+ color: hotpink;
+ }
+ ```
+
=== "app.py"
```py
import os
@@ -134,44 +123,41 @@ overwrites in the `assets` folder.
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # This is an tag
+ - components:
+ - text: |
+ # This is an tag
- ## This is an tag
+ ## This is an tag
- ###### This is an tag
- type: card
- title: Changing the header color
+ ###### This is an tag
+ type: card
+ title: Changing the header color
```
- === "Result"
- [![AssetsCSS]][AssetsCSS]
-
- [AssetsCSS]: ../../assets/user_guides/assets/css_change.png
+ === "Result"
+ [![AssetsCSS]][assetscss]
### Overwrite CSS for selected pages
-To style components for a specific page, use the page's `id` in the CSS selectors. By default, this is the
-[same as the page `title`](pages.md), but such a value might not be a valid CSS identifier.
-A suitable `id` must be unique across all models in the dashboard and should contain only alphanumeric
-characters, hyphens (`-`) and underscores (`_`). In particular, note that spaces are _not_ allowed.
+To style components for a specific page, use the page's `id` in the CSS selectors. By default, this is the [same as the page `title`](pages.md), but such a value might not be a valid CSS identifier.
+
+A suitable `id` must be unique across all models in the dashboard and should contain only alphanumeric characters, hyphens (`-`) and underscores (`_`). In particular, note that spaces are _not_ allowed.
Suppose you want to hide the page title on one page only. Here's how you can achieve this:
1. Give a valid `id` to the `Page`, for example `Page(id="page-with-hidden-title", title="Page with hidden title", ...)`.
-2. Identify the CSS class or CSS `id` you need to target. To hide the page title, you need to hide the parent container with the id `right-header`.
-3. Use the `id` to hide the content.
-4. Add your custom css file to the `assets` folder.
-
+1. Identify the CSS class or CSS `id` you need to target. To hide the page title, you need to hide the parent container with the id `right-header`.
+1. Use the `id` to hide the content.
+1. Add your custom css file to the `assets` folder.
!!! example "Hide page title on selected pages"
=== "my_css_file.css"
- ```css
- #page-with-hidden-title #right-header {
- display: none;
- }
- ```
+ ```css
+ #page-with-hidden-title #right-header {
+ display: none;
+ }
+ ```
+
=== "app.py"
```py
import vizro.models as vm
@@ -199,25 +185,24 @@ Suppose you want to hide the page title on one page only. Here's how you can ach
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Placeholder
- type: card
- title: Page with hidden title
- id: page-with-hidden-title
- - components:
- - text: |
- # Placeholder
- type: card
- title: Page with shown title
+ - components:
+ - text: |
+ # Placeholder
+ type: card
+ title: Page with hidden title
+ id: page-with-hidden-title
+ - components:
+ - text: |
+ # Placeholder
+ type: card
+ title: Page with shown title
```
- === "Result"
- [![PageTitle]][PageTitle]
-
- [PageTitle]: ../../assets/user_guides/assets/css_page_title.png
+ === "Result"
+ [![PageTitle]][pagetitle]
### Overwrite CSS for selected components
+
To adjust CSS properties for specific components, such as altering the appearance of a selected [`Card`][vizro.models.Card] rather than all Cards, you need to supply an `id` to the component you want to style.
Let's say we want to change the `background-color` and `color` of a specific `Card`.
@@ -225,41 +210,43 @@ Let's say we want to change the `background-color` and `color` of a specific `Ca
Here's how you can do it:
1. Assign a unique `id` to the relevant `Card`, for example: `Card(id="custom-card", ...)`
-2. Run your dashboard and open it in your browser
-3. View the HTML document to find the appropriate CSS class or element you need to target, as explained in the section
-on [identifying the correct CSS selector](#identify-the-correct-css-selector).
+1. Run your dashboard and open it in your browser
+1. View the HTML document to find the appropriate CSS class or element you need to target, as explained in the section on [identifying the correct CSS selector](#identify-the-correct-css-selector).
-It's essential to understand the relationship between the targeted CSS class or element and the component assigned
-`id`, for example:
+It's essential to understand the relationship between the targeted CSS class or element and the component assigned `id`, for example:
-```html title="HTML structure of a `Card`"
+
+```html title="HTML structure of a card"
-
- Lorem ipsum dolor sit amet consectetur adipisicing elit.
-
+
+
+ Lorem ipsum dolor sit amet consectetur adipisicing elit.
+
+
```
-
-* **Main element with `id`:** There is a `` with our `id="custom-card"`.
-* **Parent element:** That `` is wrapped inside a parent `` with the class name `"card"`. This is the element we need to target to change the background color.
-* **Child element:** The card text is wrapped inside a `` that is a child of the `
` with our `id`. This is the element we need to target to change the font color.
+
+- **Main element with `id`:** There is a `` with our `id="custom-card"`.
+- **Parent element:** That `` is wrapped inside a parent `` with the class name `"card"`. This is the element we need to target to change the background color.
+- **Child element:** The card text is wrapped inside a `` that is a child of the `
` with our `id`. This is the element we need to target to change the font color.
!!! example "Customizing CSS properties in selective components"
=== "my_css_file.css"
- ```css
- /* Apply styling to parent */
- .card:has(#custom-card) {
- background-color: white;
- }
+ ```css
+ /* Apply styling to parent */
+ .card:has(#custom-card) {
+ background-color: white;
+ }
+
+ /* Apply styling to child */
+ #custom-card p {
+ color: black;
+ }
+ ```
- /* Apply styling to child */
- #custom-card p {
- color: black;
- }
- ```
=== "app.py"
```py
import vizro.models as vm
@@ -285,77 +272,65 @@ It's essential to understand the relationship between the targeted CSS class or
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- Lorem ipsum dolor sit amet consectetur adipisicing elit.
- type: card
- id: custom-card
- - text: |
- Lorem ipsum dolor sit amet consectetur adipisicing elit.
- type: card
- title: Changing the card color
+ - components:
+ - text: |
+ Lorem ipsum dolor sit amet consectetur adipisicing elit.
+ type: card
+ id: custom-card
+ - text: |
+ Lorem ipsum dolor sit amet consectetur adipisicing elit.
+ type: card
+ title: Changing the card color
```
- === "Result"
- [![CardCSS]][CardCSS]
-
- [CardCSS]: ../../assets/user_guides/assets/css_change_card.png
+ === "Result"
+ [![CardCSS]][cardcss]
!!! note "Relationship between model ID and CSS ID"
+ Some Vizro components produce a single HTML element with an ID that matches the model ID, allowing you to target it directly using the CSS #id selector. Other components generate multiple HTML elements. Within these, the "core" element will have an ID matching the model ID, while non-core elements may have IDs that are variations of it, such as `{model-id}-title`.
- Some Vizro components produce a single HTML element with an ID that matches the model ID, allowing you to target it
- directly using the CSS #id selector. Other components generate multiple HTML elements. Within these, the "core"
- element will have an ID matching the model ID, while non-core elements may have IDs that are variations of it,
- such as `{model-id}-title`.
-
- In all instances, you can determine the correct selector by using Chrome DevTools or a similar tool after setting the
- appropriate model ID.
-
+ In all instances, you can determine the correct selector by using Chrome DevTools or a similar tool after setting the appropriate model ID.
## Common examples
### Make your CSS responsive to theme switches with variables
-To ensure your CSS adapts to theme changes, we recommend using CSS variables (`var`) whenever possible. For a
-comprehensive list of available variable names, refer to the
-[Bootstrap documentation](https://getbootstrap.com/docs/5.3/customize/css-variables/). Note that our
-Bootstrap stylesheet is still under development, so not all Bootstrap variables are currently available.
-Additionally, you can define your own CSS variables, as demonstrated in the example on
-[changing the container background color](#change-the-styling-of-a-container).
+
+To ensure your CSS adapts to theme changes, we recommend using CSS variables (`var`) whenever possible. For a comprehensive list of available variable names, refer to the [Bootstrap documentation](https://getbootstrap.com/docs/5.3/customize/css-variables/). Note that our Bootstrap stylesheet is still under development, so not all Bootstrap variables are currently available. Additionally, you can define your own CSS variables, as demonstrated in the example on [changing the container background color](#change-the-styling-of-a-container).
### Turn off page title
+
See the example above on [hiding the page title on selected pages](#overwrite-css-for-selected-pages).
### Change the background color of a card
+
See the example above on [customizing CSS properties in selective components](#overwrite-css-for-selected-components).
### Change the global font
+
The default fonts for a Vizro app are `Inter, sans-serif, Arial, serif`.
If you need to change the global font, perhaps to adhere to branding guidelines, follow these steps:
1. Download the desired font from a font provider such as [Google Fonts](https://fonts.google.com/).
-2. Place the font file (`.ttf`, `woff2`, etc.) into your `assets` folder. Here’s an example of what the assets folder might look like:
- 
+1. Place the font file (`.ttf`, `woff2`, etc.) into your `assets` folder. Here’s an example of what the assets folder might look like:
-3. Add the font to your CSS file using the `@font-face` rule and apply the font globally to your Vizro app, making sure
-to specify fallback fonts. Add the following to your `custom.css` file:
+ 
+1. Add the font to your CSS file using the `@font-face` rule and apply the font globally to your Vizro app, making sure to specify fallback fonts. Add the following to your `custom.css` file:
```css
@font-face {
- font-family: PlayfairDisplay;
- src: url("PlayfairDisplay-VariableFont_wght.ttf") format("truetype");
+ font-family: PlayfairDisplay;
+ src: url("PlayfairDisplay-VariableFont_wght.ttf") format("truetype");
}
* {
- font-family: PlayfairDisplay, Inter, sans-serif, Arial, serif;
+ font-family: PlayfairDisplay, Inter, sans-serif, Arial, serif;
}
```
-
-4. Note that the modification above applies solely to the dashboard font. To also change the font within the
-Plotly charts, you must specify this at the beginning of your `app.py` file:
+1. Note that the modification above applies solely to the dashboard font. To also change the font within the Plotly charts, you must specify this at the beginning of your `app.py` file:
```python
import plotly.io as pio
@@ -365,44 +340,42 @@ Plotly charts, you must specify this at the beginning of your `app.py` file:
```
### Reposition the logo
-By default, the logo appears in the top left corner of the dashboard. You can move it further to the left or right by
-adjusting the `padding` of the `#page-header` element. Here is an example of how to achieve this:
+
+By default, the logo appears in the top left corner of the dashboard. You can move it further to the left or right by adjusting the `padding` of the `#page-header` element. Here is an example of how to achieve this:
```css
#page-header {
- padding-left: 8px;
+ padding-left: 8px;
}
```
-
### Change the styling of a container
-If you want to make the subsections of your dashboard stand out more, you can do this by placing your components
-inside a [Container](container.md) and changing the container's styling, for example, background color, borders, padding, etc.
-To do this, you need to change the container's CSS class. Using the DevTool, as explained in the section on
-[identifying the correct CSS selector](#identify-the-correct-css-selector), you'll find that the CSS class for the
-`Container` is `page-component-container`. You can then use this class to set a new `background-color` and `padding`.
+If you want to make the subsections of your dashboard stand out more, you can do this by placing your components inside a [Container](container.md) and changing the container's styling, for example, background color, borders, padding, etc.
+
+To do this, you need to change the container's CSS class. Using the DevTool, as explained in the section on [identifying the correct CSS selector](#identify-the-correct-css-selector), you'll find that the CSS class for the `Container` is `page-component-container`. You can then use this class to set a new `background-color` and `padding`.
!!! example "Style a container"
=== "custom.css"
- ```css
- /* Assign a variable to the dark and light theme */
- [data-bs-theme="dark"] {
- --container-bg-color: #232632;
- }
-
- [data-bs-theme="light"] {
- --container-bg-color: #F5F6F6;
- }
+ ```css
+ /* Assign a variable to the dark and light theme */
+ [data-bs-theme="dark"] {
+ --container-bg-color: #232632;
+ }
+
+ [data-bs-theme="light"] {
+ --container-bg-color: #F5F6F6;
+ }
+
+ /* Use the custom variable var(--container-bg-color) */
+ .page-component-container {
+ background: var(--container-bg-color);
+ padding: 12px;
+ }
+ ```
- /* Use the custom variable var(--container-bg-color) */
- .page-component-container {
- background: var(--container-bg-color);
- padding: 12px;
- }
- ```
=== "app.py"
```py
import vizro.models as vm
@@ -437,12 +410,12 @@ To do this, you need to change the container's CSS class. Using the DevTool, as
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - title: "Page with subsections"
+ - title: Page with subsections
layout:
grid: [[0, 1]]
components:
- type: container
- title: "Container I"
+ title: Container I
components:
- type: graph
figure:
@@ -452,7 +425,7 @@ To do this, you need to change the container's CSS class. Using the DevTool, as
y: sepal_length
color: species
- type: container
- title: "Container II"
+ title: Container II
components:
- type: graph
figure:
@@ -462,13 +435,11 @@ To do this, you need to change the container's CSS class. Using the DevTool, as
y: sepal_length
color: species
```
- === "Result"
- [![StyleContainer]][StyleContainer]
- [StyleContainer]: ../../assets/user_guides/custom_css/style-container.png
+ === "Result"
+ [![StyleContainer]][stylecontainer]
-You will notice that the background colors of the charts are different. To align it with the colors of the container,
-you can make the charts' background transparent.
+You will notice that the background colors of the charts are different. To align it with the colors of the container, you can make the charts' background transparent.
To make the background of all charts transparent:
@@ -492,3 +463,8 @@ def custom_chart(data_frame):
```
+
+[assetscss]: ../../assets/user_guides/assets/css_change.png
+[cardcss]: ../../assets/user_guides/assets/css_change_card.png
+[pagetitle]: ../../assets/user_guides/assets/css_page_title.png
+[stylecontainer]: ../../assets/user_guides/custom_css/style-container.png
diff --git a/vizro-core/docs/pages/user-guides/custom-figures.md b/vizro-core/docs/pages/user-guides/custom-figures.md
index f135127be..3a178932f 100644
--- a/vizro-core/docs/pages/user-guides/custom-figures.md
+++ b/vizro-core/docs/pages/user-guides/custom-figures.md
@@ -1,41 +1,36 @@
# How to create custom figures
-This guide explains how to create custom figures, which is useful when you need a component that reacts to
-[filter](filters.md) and [parameter](parameters.md) controls.
+This guide explains how to create custom figures, which is 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).
## When to use a custom figure
-As described in the flowchart detailing [when to use `Figure`](figure.md), custom figures should be used if
-**both** of the following conditions are met:
+
+As described in the flowchart detailing [when to use `Figure`](figure.md), custom figures should be used if **both** of the following conditions are met:
- You need a figure that doesn't fit into the existing pre-defined components ([`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid]).
- You need a figure that isn't available in our pre-defined figure functions [`vizro.figures`](../API-reference/figure-callables.md).
## Steps to create a custom figure
-1. Define a function that returns a [Dash component](https://dash.plotly.com/#open-source-component-libraries).
-This can, but does not need to, be based on code in our pre-defined figure functions in [`vizro.figures`](../API-reference/figure-callables.md).
-2. Decorate it with `@capture("figure")`.
-3. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
-4. The figure should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments
-will not react to dashboard controls such as [`Filter`](filters.md).
-5. Pass your function to the `figure` argument of the [`Figure`][vizro.models.Figure] model.
+1. Define a function that returns a [Dash component](https://dash.plotly.com/#open-source-component-libraries). This can, but does not need to, be based on code in our pre-defined figure functions in [`vizro.figures`](../API-reference/figure-callables.md).
+1. Decorate it with `@capture("figure")`.
+1. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
+1. The figure should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments will not react to dashboard controls such as [`Filter`](filters.md).
+1. Pass your function to the `figure` argument of the [`Figure`][vizro.models.Figure] model.
The following examples can be used as a base to build more sophisticated figures.
## Examples of custom figures
### Custom KPI card
-To change the design or content of our existing KPI (key performance indicator) cards from
-[`vizro.figures`](../API-reference/figure-callables.md), you can do so by following the steps described above.
-For instance, to make a KPI card with the icon positioned on the right side of the title instead of the left,
-copy and paste the [source code of `kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card) and
-adjust the return statement of the function.
+To change the design or content of our existing KPI (key performance indicator) cards from [`vizro.figures`](../API-reference/figure-callables.md), you can do so by following the steps described above.
+
+For instance, to make a KPI card with the icon positioned on the right side of the title instead of the left, copy and paste the [source code of `kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card) and adjust the return statement of the function.
+
!!! example "Custom KPI card"
=== "app.py"
```{.python pycafe-link}
@@ -107,29 +102,26 @@ adjust the return statement of the function.
```
1. Here we decorate our custom figure function with the `@capture("figure")` decorator.
- 2. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
- 3. We adjust the return statement to include the icon on the right side of the title. This is achieved by swapping the order of the `html.H2` and `html.P` compared to the original `kpi_card`.
- 4. This creates a [`layout`](layouts.md) with four rows and columns. The KPI cards are positioned in the first two cells, while the remaining cells are empty.
- 5. For more information, refer to the API reference for the [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card).
- 6. Our custom figure function `custom_kpi_card` now needs to be passed on to the `vm.Figure`.
+ 1. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
+ 1. We adjust the return statement to include the icon on the right side of the title. This is achieved by swapping the order of the `html.H2` and `html.P` compared to the original `kpi_card`.
+ 1. This creates a [`layout`](layouts.md) with four rows and columns. The KPI cards are positioned in the first two cells, while the remaining cells are empty.
+ 1. For more information, refer to the API reference for the [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card).
+ 1. Our custom figure function `custom_kpi_card` now needs to be passed on to the `vm.Figure`.
=== "app.yaml"
- ```yaml
- # Custom figures are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomKPI]][CustomKPI]
+ Custom figures are currently only possible via Python configuration.
- [CustomKPI]: ../../assets/user_guides/figure/custom_kpi.png
+ === "Result"
+ [![CustomKPI]][customkpi]
### Dynamic HTML header
-You can create a custom figure for any [Dash component](https://dash.plotly.com/#open-source-component-libraries).
-Below is an example of a custom figure that returns a `html.H2` component that dynamically updates based on the selected
-name from a filter.
+
+You can create a custom figure for any [Dash component](https://dash.plotly.com/#open-source-component-libraries). Below is an example of a custom figure that returns a `html.H2` component that dynamically updates based on the selected name from a filter.
+
!!! example "Dynamic HTML header"
=== "app.py"
```{.python pycafe-link}
@@ -159,27 +151,24 @@ name from a filter.
```
1. Here we decorate our custom figure function with the `@capture("figure")` decorator.
- 2. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
- 3. We return a `html.H2` component that dynamically updates based on the selected name from the filter.
- 4. Our custom figure function `dynamic_html_header` now needs to be passed on to the `vm.Figure`.
+ 1. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
+ 1. We return a `html.H2` component that dynamically updates based on the selected name from the filter.
+ 1. Our custom figure function `dynamic_html_header` now needs to be passed on to the `vm.Figure`.
=== "app.yaml"
- ```yaml
- # Custom figures are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomHTML]][CustomHTML]
+ Custom figures are currently only possible via Python configuration.
- [CustomHTML]: ../../assets/user_guides/figure/custom_html.png
+ === "Result"
+ [![CustomHTML]][customhtml]
-
### Dynamic number of cards
-The example below shows how to create multiple cards created from a `pandas.DataFrame` where the
-number of cards displayed dynamically adjusts based on a `vm.Parameter`.
+
+The example below shows how to create multiple cards created from a `pandas.DataFrame` where the number of cards displayed dynamically adjusts based on a `vm.Parameter`.
+
!!! example "Dynamic number of cards"
=== "app.py"
```py
@@ -239,40 +228,39 @@ number of cards displayed dynamically adjusts based on a `vm.Parameter`.
```
1. Here we decorate our custom figure function with the `@capture("figure")` decorator.
- 2. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
- 3. Our decorated figure function `multiple_cards` now needs to be passed on to the `vm.Figure`.
- 4. We add a [`vm.Parameter`](parameters.md) to dynamically adjust the number of cards displayed.
- The parameter targets the `n_rows` argument of the `multiple_cards` function, determining the number of rows
- taken from the data.
+ 1. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
+ 1. Our decorated figure function `multiple_cards` now needs to be passed on to the `vm.Figure`.
+ 1. We add a [`vm.Parameter`](parameters.md) to dynamically adjust the number of cards displayed. The parameter targets the `n_rows` argument of the `multiple_cards` function, determining the number of rows taken from the data.
Run and edit this code in PyCafe
=== "styling.css"
```css
.multiple-cards-container {
- display: flex;
- flex-wrap: wrap;
- gap: 12px;
+ display: flex;
+ flex-wrap: wrap;
+ gap: 12px;
}
.figure-container {
- height: unset;
- width: unset;
+ height: unset;
+ width: unset;
}
.figure-container .card {
- height: 210px;
- width: 240px;
+ height: 210px;
+ width: 240px;
}
```
- === "app.yaml"
- ```yaml
- # Custom figures are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomFigure]][CustomFigure]
- [CustomFigure]: ../../assets/user_guides/figure/custom_multiple_cards.png
+ === "app.yaml"
+ Custom figures are currently only possible via Python configuration.
+ === "Result"
+ [![CustomFigure]][customfigure]
+
+[customfigure]: ../../assets/user_guides/figure/custom_multiple_cards.png
+[customhtml]: ../../assets/user_guides/figure/custom_html.png
+[customkpi]: ../../assets/user_guides/figure/custom_kpi.png
diff --git a/vizro-core/docs/pages/user-guides/custom-tables.md b/vizro-core/docs/pages/user-guides/custom-tables.md
index e990cfbb0..42748820b 100644
--- a/vizro-core/docs/pages/user-guides/custom-tables.md
+++ b/vizro-core/docs/pages/user-guides/custom-tables.md
@@ -1,21 +1,18 @@
# How to create custom Dash AG Grids and Dash DataTables
-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.
+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.
-The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] model accept the `figure` argument, where you can enter
-_any_ [`dash_ag_grid`][vizro.tables.dash_ag_grid] or [`dash_data_table`][vizro.tables.dash_data_table] chart as explained in the [user guide on tables](table.md).
+The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] model accept the `figure` argument, where you can enter _any_ [`dash_ag_grid`][vizro.tables.dash_ag_grid] or [`dash_data_table`][vizro.tables.dash_data_table] chart as explained in the [user guide on tables](table.md).
One reason could be that you want to create a table/grid that requires computations that can be controlled by parameters (see the example below).
### Steps to create a custom table
1. Define a function that returns a `dash_ag_grid.AgGrid` or `dash_table.DataTable` object.
-2. Decorate it with `@capture("ag_grid")` or `@capture("table")`.
-3. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
-4. The table should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments
-will not react to dashboard controls such as [`Filter`](filters.md).
-5. Pass your function to the `figure` argument of the [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid] model.
+1. Decorate it with `@capture("ag_grid")` or `@capture("table")`.
+1. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
+1. The table should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments will not react to dashboard controls such as [`Filter`](filters.md).
+1. Pass your function to the `figure` argument of the [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid] model.
The following examples show a possible version of a custom table. In this case the argument `chosen_columns` was added, which you can control with a parameter:
@@ -70,14 +67,12 @@ The following examples show a possible version of a custom table. In this case t
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
- ```yaml
- # Custom tables are currently only possible via Python configuration
- ```
- === "Result"
- [![Table3]][Table3]
+ Custom tables are currently only possible via Python configuration.
- [Table3]: ../../assets/user_guides/table/custom_table.png
+ === "Result"
+ [![Table3]][table3]
??? example "Custom Dash AgGrid"
=== "app.py"
@@ -136,11 +131,12 @@ The following examples show a possible version of a custom table. In this case t
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
- ```yaml
- # Custom Ag Grids are currently only possible via Python configuration
- ```
+ Custom Ag Grids are currently only possible via Python configuration.
+
=== "Result"
- [![GridCustom]][GridCustom]
+ [![GridCustom]][gridcustom]
- [GridCustom]: ../../assets/user_guides/table/custom_grid.png
+[gridcustom]: ../../assets/user_guides/table/custom_grid.png
+[table3]: ../../assets/user_guides/table/custom_table.png
diff --git a/vizro-core/docs/pages/user-guides/dashboard.md b/vizro-core/docs/pages/user-guides/dashboard.md
index 0b37e03fa..244f65256 100644
--- a/vizro-core/docs/pages/user-guides/dashboard.md
+++ b/vizro-core/docs/pages/user-guides/dashboard.md
@@ -1,16 +1,15 @@
# How to create a dashboard
-This guide shows you how to configure and call a [`Dashboard`][vizro.models.Dashboard] using either
-pydantic models, Python dictionaries, YAML, or JSON.
+
+This guide shows you how to configure and call a [`Dashboard`][vizro.models.Dashboard] using either pydantic models, Python dictionaries, YAML, or JSON.
To create a dashboard:
1. Choose one of the possible configuration syntaxes
-2. Create your `pages`, see our [guide on Pages](pages.md)
-3. (optional) Choose a `theme`, see our [guide on Themes](themes.md)
-4. (optional) Customize your `navigation`, see our [guide on Navigation](navigation.md)
-5. (optional) Set a `title` for your dashboard
-6. Add your `dashboard` to the `build` call of Vizro
-
+1. Create your `pages`, see our [guide on Pages](pages.md)
+1. (optional) Choose a `theme`, see our [guide on Themes](themes.md)
+1. (optional) Customize your `navigation`, see our [guide on Navigation](navigation.md)
+1. (optional) Set a `title` for your dashboard
+1. Add your `dashboard` to the `build` call of Vizro
## Use dashboard configuration options
@@ -37,6 +36,7 @@ To create a dashboard:
Vizro().build(dashboard).run()
```
+
=== "app.py - Python dict"
```py
import vizro.plotly.express as px
@@ -77,6 +77,7 @@ To create a dashboard:
Vizro().build(dashboard).run()
```
+
=== "dashboard.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -101,50 +102,49 @@ To create a dashboard:
type: filter
title: My first dashboard
```
+
=== "dashboard.json"
```json
{
- "pages": [
+ "pages": [
+ {
+ "components": [
+ {
+ "figure": {
+ "_target_": "scatter",
+ "color": "species",
+ "data_frame": "iris",
+ "x": "sepal_length",
+ "y": "petal_width"
+ },
+ "type": "graph"
+ },
{
- "components": [
- {
- "figure": {
- "_target_": "scatter",
- "color": "species",
- "data_frame": "iris",
- "x": "sepal_length",
- "y": "petal_width"
- },
- "type": "graph"
- },
- {
- "figure": {
- "_target_": "histogram",
- "color": "species",
- "data_frame": "iris",
- "x": "sepal_width",
- },
- "type": "graph"
- }
- ],
- "controls": [
- {
- "column": "species",
- "type": "filter"
- }
- ],
- "title": "My first dashboard"
+ "figure": {
+ "_target_": "histogram",
+ "color": "species",
+ "data_frame": "iris",
+ "x": "sepal_width"
+ },
+ "type": "graph"
}
- ]
+ ],
+ "controls": [
+ {
+ "column": "species",
+ "type": "filter"
+ }
+ ],
+ "title": "My first dashboard"
+ }
+ ]
}
```
- === "Result"
- [![Dashboard]][Dashboard]
- [Dashboard]: ../../assets/user_guides/dashboard/dashboard.png
+ === "Result"
+ [![Dashboard]][dashboard]
!!! note "Extra `.py` files for `yaml` and `json` required"
-
Note that in the `yaml` and `json` example an extra `.py` is required to register the data and parse the yaml/json configuration.
=== "app.py for yaml"
@@ -164,6 +164,7 @@ To create a dashboard:
Vizro().build(dashboard).run()
```
+
=== "app.py for json"
```py
import json
@@ -187,7 +188,6 @@ After running the dashboard, you can access the dashboard via `localhost:8050`.
If supplied, the `title` of the [`Dashboard`][vizro.models.Dashboard] displays a heading at the top of every page.
-
## Add a dashboard logo
Vizro will [automatically incorporate the dashboard logo](assets.md/#add-a-logo-image) in the top-left corner of each page if an image named `logo.` is present within the assets folder.
@@ -196,11 +196,10 @@ Vizro will [automatically incorporate the dashboard logo](assets.md/#add-a-logo-
## Browser title
-The [website icon](assets.md/#change-the-favicon), Dashboard `title` (if supplied) and [Page `title`][vizro.models.Page] are displayed in the browser's
-title bar. For example, if your Dashboard `title` is "Vizro Demo" and the Page `title` is "Homepage", then the title in the browser tab will be "Vizro Demo: Homepage".
+The [website icon](assets.md/#change-the-favicon), Dashboard `title` (if supplied) and [Page `title`][vizro.models.Page] are displayed in the browser's title bar. For example, if your Dashboard `title` is "Vizro Demo" and the Page `title` is "Homepage", then the title in the browser tab will be "Vizro Demo: Homepage".
## Meta tags for social media
-Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat
-clients. The preview includes the `URL`, `title`, plus an [image](assets.md/#include-a-meta-tags-image) and
-[Page `description`][vizro.models.Page] (if supplied). To see an example, try sharing an example from the [Vizro examples gallery](https://vizro.mckinsey.com/).
+Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat clients. The preview includes the `URL`, `title`, plus an [image](assets.md/#include-a-meta-tags-image) and [Page `description`][vizro.models.Page] (if supplied). To see an example, try sharing an example from the [Vizro examples gallery](https://vizro.mckinsey.com/).
+
+[dashboard]: ../../assets/user_guides/dashboard/dashboard.png
diff --git a/vizro-core/docs/pages/user-guides/data.md b/vizro-core/docs/pages/user-guides/data.md
index 51bf84b97..d19b8aafb 100644
--- a/vizro-core/docs/pages/user-guides/data.md
+++ b/vizro-core/docs/pages/user-guides/data.md
@@ -2,11 +2,12 @@
Vizro supports two different types of data:
-* [Static data](#static-data): pandas DataFrame. This is the simplest method and best to use if you do not need the more advanced functionality of dynamic data.
-* [Dynamic data](#dynamic-data): function that returns a pandas DataFrame. This is a bit more complex to understand but has more advanced functionality such as the ability to refresh data while the dashboard is running.
+- [Static data](#static-data): pandas DataFrame. This is the simplest method and best to use if you do not need the more advanced functionality of dynamic data.
+- [Dynamic data](#dynamic-data): function that returns a pandas DataFrame. This is a bit more complex to understand but has more advanced functionality such as the ability to refresh data while the dashboard is running.
The following flowchart shows what you need to consider when choosing how to set up your data.
-``` mermaid
+
+```mermaid
graph TD
refresh["`Do you need your data to refresh while the dashboard is running?`"]
specification["`Do you need to specify your dashboard through a configuration language like YAML?`"]
@@ -27,11 +28,10 @@ graph TD
```
??? note "Static vs. dynamic data comparison"
-
This table gives a full comparison between static and dynamic data. Do not worry if you do not yet understand everything in it; it will become clearer after reading more about [static data](#static-data) and [dynamic data](#dynamic-data)!
| | Static | Dynamic |
- |---------------------------------------------------------------|------------------|------------------------------------------|
+ | ------------------------------------------------------------- | ---------------- | ---------------------------------------- |
| Required Python type | pandas DataFrame | Function that returns a pandas DataFrame |
| Can be supplied directly in `data_frame` argument of `figure` | Yes | No |
| Can be referenced by name after adding to data manager | Yes | Yes |
@@ -73,14 +73,13 @@ The below example uses the Iris data saved to a file `iris.csv` in the same dire
```
1. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
- === "Result"
- [![DataBasic]][DataBasic]
- [DataBasic]: ../../assets/user_guides/data/data_pandas_dataframe.png
+ === "Result"
+ [![DataBasic]][databasic]
The [`Graph`][vizro.models.Graph], [`AgGrid`][vizro.models.AgGrid] and [`Table`][vizro.models.Table] models all have an argument called `figure`. This accepts a function (in the above example, `px.scatter`) that takes a pandas DataFrame as its first argument. The name of this argument is always `data_frame`. When configuring the dashboard using Python, it is optional to give the name of the argument: if you like, you could write `data_frame=iris` instead of `iris`.
-!!! note
+!!! note
With static data, once the dashboard is running, the data shown in the dashboard cannot change even if the source data in `iris.csv` changes. The code `iris = pd.read_csv("iris.csv")` is only executed once when the dashboard is first started. If you would like changes to source data to flow through to the dashboard then you must use [dynamic data](#dynamic-data).
### Reference by name
@@ -107,27 +106,27 @@ If you would like to specify your dashboard configuration through YAML then you
```
1. `"iris"` is the name of a data source added to the data manager. This data is a pandas DataFrame created by reading from the CSV file `iris.csv`.
+
=== "dashboard.yaml"
```yaml
pages:
- - components:
- - figure:
+ - components:
+ figure:
_target_: box
data_frame: iris # (1)!
x: species
y: petal_width
color: species
type: graph
- title: Static data example
+ title: Static data example
```
1. Refer to the `"iris"` data source in the data manager.
- === "Result"
- [![DataBasic]][DataBasic]
- [DataBasic]: ../../assets/user_guides/data/data_pandas_dataframe.png
+ === "Result"
+ [![DataBasic]][databasic]
-It is also possible to refer to a named data source using the Python API: `px.scatter("iris", ...)` or `px.scatter(data_frame="iris", ...)` would work if the `"iris"` data source has been registered in the data manager.
+It is also possible to refer to a named data source using the Python API: `px.scatter("iris", ...)` or `px.scatter(data_frame="iris", ...)` would work if the `"iris"` data source has been registered in the data manager.
## Dynamic data
@@ -166,14 +165,12 @@ The example below shows how data is fetched dynamically every time the page is r
```
1. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
- 2. To demonstrate that dynamic data can change when the page is refreshed, select 50 points at random. This simulates what would happen if your file `iris.csv` were constantly changing.
- 3. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()`; doing so would result in static data that cannot be reloaded.
- 4. Dynamic data is referenced by the name of the data source `"iris"`.
+ 1. To demonstrate that dynamic data can change when the page is refreshed, select 50 points at random. This simulates what would happen if your file `iris.csv` were constantly changing.
+ 1. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()`; doing so would result in static data that cannot be reloaded.
+ 1. Dynamic data is referenced by the name of the data source `"iris"`.
=== "Result"
- [![DynamicData]][DynamicData]
-
- [DynamicData]: ../../assets/user_guides/data/dynamic_data.gif
+ [![DynamicData]][dynamicdata]
Since dynamic data sources must always be added to the data manager and referenced by name, they may be used in YAML configuration [exactly the same way as for static data sources](#reference-by-name).
@@ -184,10 +181,10 @@ By default, a dynamic data function executes every time the dashboard is refresh
The Vizro data manager has a server-side caching mechanism to help solve this. Vizro's cache uses [Flask-Caching](https://flask-caching.readthedocs.io/en/latest/), which supports a number of possible cache backends and [configuration options](https://flask-caching.readthedocs.io/en/latest/#configuring-flask-caching). By default, the cache is turned off.
+
In a development environment the easiest way to enable caching is to use a [simple memory cache](https://cachelib.readthedocs.io/en/stable/simple/) with the default configuration options. This is achieved by adding one line to the above example to set `data_manager.cache`:
!!! example "Simple cache with default timeout of 5 minutes"
-
```py hl_lines="13"
from flask_caching import Cache
from vizro import Vizro
@@ -225,7 +222,6 @@ data_manager.cache = Cache(config={"CACHE_TYPE": "SimpleCache", "CACHE_DEFAULT_T
```
!!! warning
-
Simple cache exists purely for single-process development purposes and is not intended to be used in production. If you deploy with multiple workers, [for example with Gunicorn](run.md/#gunicorn), then you should use a production-ready cache backend. All of Flask-Caching's [built-in backends](https://flask-caching.readthedocs.io/en/latest/#built-in-cache-backends) other than `SimpleCache` are suitable for production. In particular, you might like to use [`FileSystemCache`](https://cachelib.readthedocs.io/en/stable/file/) or [`RedisCache`](https://cachelib.readthedocs.io/en/stable/redis/):
```py title="Production-ready caches"
@@ -239,7 +235,9 @@ data_manager.cache = Cache(config={"CACHE_TYPE": "SimpleCache", "CACHE_DEFAULT_T
Since Flask-Caching relies on [`pickle`](https://docs.python.org/3/library/pickle.html), which can execute arbitrary code during unpickling, you should not cache data from untrusted sources. Doing so [could be unsafe](https://github.com/pallets-eco/flask-caching/pull/209).
Note that when a production-ready cache backend is used, the cache is persisted beyond the Vizro process and is not cleared by restarting your server. To clear the cache then you must do so manually, for example, if you use `FileSystemCache` then you would delete your `cache` directory. Persisting the cache can also be useful for development purposes when handling data that takes a long time to load: even if you do not need the data to refresh while your dashboard is running, it can speed up your development loop to use dynamic data with a cache that is persisted between repeated runs of Vizro.
+
+
#### Set timeouts
You can change the timeout of the cache independently for each dynamic data source in the data manager using the `timeout` setting (measured in seconds). A `timeout` of 0 indicates that the cache does not expire. This is effectively the same as using [static data](#static-data).
@@ -278,8 +276,8 @@ In general, a parametrized dynamic data source should always return a pandas Dat
To add a parameter to control a dynamic data source, do the following:
1. add the appropriate argument to your dynamic data function and specify a default value for the argument.
-2. give an `id` to all components that have the data source you wish to alter through a parameter.
-3. [add a parameter](parameters.md) with `targets` of the form `.data_frame.` and a suitable [selector](selectors.md).
+1. give an `id` to all components that have the data source you wish to alter through a parameter.
+1. [add a parameter](parameters.md) with `targets` of the form `.data_frame.` and a suitable [selector](selectors.md).
For example, let us extend the [dynamic data example](#dynamic-data) above into an example of how parametrized dynamic data works. The `load_iris_data` can take an argument `number_of_points` controlled from the dashboard with a [`Slider`][vizro.models.Slider].
@@ -318,21 +316,18 @@ For example, let us extend the [dynamic data example](#dynamic-data) above into
```
1. `load_iris_data` takes a single argument, `number_of_points`, with a default value of 10.
- 2. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
- 3. Sample points at random, where `number_of_points` gives the number of points selected.
- 4. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()` or `load_iris_data(number_of_points=...)`; doing so would result in static data that cannot be reloaded.
- 5. Give the `vm.Graph` component `id="graph"` so that the `vm.Parameter` can target it. Dynamic data is referenced by the name of the data source `"iris"`.
- 6. Create a `vm.Parameter` to target the `number_of_points` argument for the `data_frame` used in `graph`.
+ 1. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
+ 1. Sample points at random, where `number_of_points` gives the number of points selected.
+ 1. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()` or `load_iris_data(number_of_points=...)`; doing so would result in static data that cannot be reloaded.
+ 1. Give the `vm.Graph` component `id="graph"` so that the `vm.Parameter` can target it. Dynamic data is referenced by the name of the data source `"iris"`.
+ 1. Create a `vm.Parameter` to target the `number_of_points` argument for the `data_frame` used in `graph`.
=== "Result"
- [![ParametrizedDynamicData]][ParametrizedDynamicData]
-
- [ParametrizedDynamicData]: ../../assets/user_guides/data/parametrized_dynamic_data.gif
+ [![ParametrizedDynamicData]][parametrizeddynamicdata]
Parametrized data loading is compatible with [caching](#configure-cache). The cache uses [memoization](https://flask-caching.readthedocs.io/en/latest/#memoization), so that the dynamic data function's arguments are included in the cache key. This means that `load_iris_data(number_of_points=10)` is cached independently of `load_iris_data(number_of_points=20)`.
!!! warning
-
You should always [treat the content of user input as untrusted](https://community.plotly.com/t/writing-secure-dash-apps-community-thread/54619). For example, you should not expose a filepath to load without passing it through a function like [`werkzeug.utils.secure_filename`](https://werkzeug.palletsprojects.com/en/3.0.x/utils/#werkzeug.utils.secure_filename), or you might enable arbitrary access to files on your server.
You cannot pass [nested parameters](parameters.md#nested-parameters) to dynamic data. You can only target the top-level arguments of the data loading function, not the nested keys in a dictionary.
@@ -354,7 +349,6 @@ When the page is refreshed, the behavior of a dynamic filter is as follows:
For example, let us add two filters to the [dynamic data example](#dynamic-data) above:
!!! example "Dynamic filters"
-
```py hl_lines="10 20 21"
from vizro import Vizro
import pandas as pd
@@ -386,8 +380,8 @@ For example, let us add two filters to the [dynamic data example](#dynamic-data)
```
1. We sample only 5 rather than 50 points so that changes to the available values in the filtered columns are more apparent when the page is refreshed.
- 2. This filter implicitly controls the dynamic data source `"iris"`, which supplies the `data_frame` to the targeted `vm.Graph`. On page refresh, Vizro reloads this data, finds all the unique values in the `"species"` column and sets the categorical selector's `options` accordingly.
- 3. Similarly, on page refresh, Vizro finds the minimum and maximum values of the `"sepal_length"` column in the reloaded data and sets new `min` and `max` values for the numerical selector accordingly.
+ 1. This filter implicitly controls the dynamic data source `"iris"`, which supplies the `data_frame` to the targeted `vm.Graph`. On page refresh, Vizro reloads this data, finds all the unique values in the `"species"` column and sets the categorical selector's `options` accordingly.
+ 1. Similarly, on page refresh, Vizro finds the minimum and maximum values of the `"sepal_length"` column in the reloaded data and sets new `min` and `max` values for the numerical selector accordingly.
Consider a filter that depends on dynamic data, where you do **not** want the available values to change when the dynamic data changes. You should manually specify the `selector`'s `options` field (categorical selector) or `min` and `max` fields (numerical selector). In the above example, this could be achieved as follows:
@@ -409,10 +403,13 @@ controls = [
When Vizro initially builds a filter that depends on parametrized dynamic data loading, data is loaded using the default argument values. This data is used to:
-* perform initial validation
-* check which data sources contain the specified `column` (unless `targets` is explicitly specified) and
-* find the type of selector to use (unless `selector` is explicitly specified).
+- perform initial validation
+- check which data sources contain the specified `column` (unless `targets` is explicitly specified) and
+- find the type of selector to use (unless `selector` is explicitly specified).
!!! note
-
When the value of a dynamic data parameter is changed by a dashboard user, the data underlying a dynamic filter can change. Currently this change affects page components such as `vm.Graph` but does not affect the available values shown in a dynamic filter, which only update on page refresh. This functionality will be coming soon!
+
+[databasic]: ../../assets/user_guides/data/data_pandas_dataframe.png
+[dynamicdata]: ../../assets/user_guides/data/dynamic_data.gif
+[parametrizeddynamicdata]: ../../assets/user_guides/data/parametrized_dynamic_data.gif
diff --git a/vizro-core/docs/pages/user-guides/extensions.md b/vizro-core/docs/pages/user-guides/extensions.md
index 2c7efc9ac..74a740448 100644
--- a/vizro-core/docs/pages/user-guides/extensions.md
+++ b/vizro-core/docs/pages/user-guides/extensions.md
@@ -2,64 +2,49 @@
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).
+- **[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.
+- **[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.
-* **[CSS customizations](#css-customizations)**. You can add custom CSS to any Vizro dashboard, enabling users to deviate from the default styling and create a unique look and feel for their dashboard.
-
-* **[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
+- **[CSS customizations](#css-customizations)**. You can add custom CSS to any Vizro dashboard, enabling users to deviate from the default styling and create a unique look and feel for their dashboard.
+- **[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
-
+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)).
+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.
-
+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).
+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
+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:
+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
@@ -93,14 +78,12 @@ enabling an interaction between data points in a scatter plot and the content of
## CSS customizations
-Vizro is opinionated about visual formatting, and some elements, such as the layout of the navigation and controls,
-are fixed. You can customize some settings such as background colors, fonts, and other styles via CSS overrides.
+Vizro is opinionated about visual formatting, and some elements, such as the layout of the navigation and controls, are fixed. You can customize some settings such as background colors, fonts, and other styles via CSS overrides.
For more information, see our documentation on [customizing CSS](custom-css.md)
## 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
+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)
diff --git a/vizro-core/docs/pages/user-guides/figure.md b/vizro-core/docs/pages/user-guides/figure.md
index 0589fad3b..03bfa412a 100644
--- a/vizro-core/docs/pages/user-guides/figure.md
+++ b/vizro-core/docs/pages/user-guides/figure.md
@@ -1,26 +1,19 @@
# How to use figures
-This guide shows you how to add any [Dash component](https://dash.plotly.com/#open-source-component-libraries) that needs to be reactive to [filter](filters.md) and [parameter](parameters.md) controls.
-If you want to add a static Dash component to your page, use [custom components](custom-components.md) instead.
+This guide shows you how to add any [Dash component](https://dash.plotly.com/#open-source-component-libraries) that needs to be reactive to [filter](filters.md) and [parameter](parameters.md) controls. If you want to add a static Dash component to your page, use [custom components](custom-components.md) instead.
-[`Figure`][vizro.models.Figure] provides a flexible foundation for all types of reactive Dash components in Vizro.
-The [`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] and [`AgGrid`][vizro.models.AgGrid] components are
-specific implementations of `Figure`. They serve as intuitive shortcuts, embedding behaviors and interactions specific
-to their purposes.
+[`Figure`][vizro.models.Figure] provides a flexible foundation for all types of reactive Dash components in Vizro. The [`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] and [`AgGrid`][vizro.models.AgGrid] components are specific implementations of `Figure`. They serve as intuitive shortcuts, embedding behaviors and interactions specific to their purposes.
-If these more specific models already achieve what you need then they should be used in preference to
-the more generic `Figure`. Remember that it is possible to supply [custom charts](custom-charts.md) to `Graph`
-and [custom tables](custom-tables.md) to `Table`.
+If these more specific models already achieve what you need then they should be used in preference to the more generic `Figure`. Remember that it is possible to supply [custom charts](custom-charts.md) to `Graph` and [custom tables](custom-tables.md) to `Table`.
-There are already a few figure functions you can reuse, see the section on [KPI cards](#key-performance-indicator-kpi-cards)
-for more details:
+There are already a few figure functions you can reuse, see the section on [KPI cards](#key-performance-indicator-kpi-cards) for more details:
- [`kpi_card`][vizro.figures.kpi_card]
- [`kpi_card_reference`][vizro.figures.kpi_card_reference]
The following flowchart shows what you need to consider when choosing which model to use:
-``` mermaid
+```mermaid
graph TD
first["`Does your desired component exist in Vizro, e.g. Graph, Table or AgGrid?`"]
specific-component([Use the specific component])
@@ -40,14 +33,12 @@ graph TD
classDef clickable color:#4051b5;
```
-
To add a `Figure` to your page:
1. Add the `Figure` model to the components argument of the [Page][vizro.models.Page] model.
-2. Use an existing figure function from [`vizro.figures`](../API-reference/figure-callables.md) and pass it to the `figure` argument of the `Figure` model.
+1. Use an existing figure function from [`vizro.figures`](../API-reference/figure-callables.md) and pass it to the `figure` argument of the `Figure` model.
!!! example "Use existing figure functions"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -99,40 +90,25 @@ To add a `Figure` to your page:
selector:
type: radio_items
layout:
- grid:
- [
- [0, -1, -1, -1],
- [-1, -1, -1, -1],
- [-1, -1, -1, -1],
- [-1, -1, -1, -1],
- [-1, -1, -1, -1],
- ]
+ grid: [[0, -1, -1, -1], [-1, -1, -1, -1], [-1, -1, -1, -1], [-1, -1, -1, -1],
+ [-1, -1, -1, -1]]
title: KPI card
```
- === "Result"
- [![Figure]][Figure]
-
- [Figure]: ../../assets/user_guides/figure/figure.png
+ === "Result"
+ [![Figure]][figure]
### Key Performance Indicator (KPI) cards
-A KPI card is a dynamic card that can display a single value, but optionally, can also include a title, icon, and reference value.
-It is a common visual component to display key metrics in a dashboard. Vizro supports two pre-defined KPI card functions:
-- [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card): A KPI card that shows a single value found
-by performing an aggregation function (by default, `sum`) over a specified column.
-Required arguments are `data_frame` and `value_column`.
+A KPI card is a dynamic card that can display a single value, but optionally, can also include a title, icon, and reference value. It is a common visual component to display key metrics in a dashboard. Vizro supports two pre-defined KPI card functions:
-- [`kpi_card_with_reference`](../API-reference/figure-callables.md#vizro.figures.kpi_card_reference): A KPI card that shows a single value
-and a delta comparison to a reference value found by performing an aggregation function (by default, `sum`) over the specified columns.
-Required arguments are `data_frame`, `value_column` and `reference_column`.
+- [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card): A KPI card that shows a single value found by performing an aggregation function (by default, `sum`) over a specified column. Required arguments are `data_frame` and `value_column`.
-As described in the [API reference](../API-reference/figure-callables.md) and illustrated in the below example, these
-functions have several arguments to customize your KPI cards. If you require a level of customization that is not
-possible with the built-in functions then you can create a [custom figure](custom-figures.md).
+- [`kpi_card_with_reference`](../API-reference/figure-callables.md#vizro.figures.kpi_card_reference): A KPI card that shows a single value and a delta comparison to a reference value found by performing an aggregation function (by default, `sum`) over the specified columns. Required arguments are `data_frame`, `value_column` and `reference_column`.
-!!! example "KPI card variations"
+As described in the [API reference](../API-reference/figure-callables.md) and illustrated in the below example, these functions have several arguments to customize your KPI cards. If you require a level of customization that cannot be done with the built-in functions then you can create a [custom figure](custom-figures.md).
+!!! example "KPI card variations"
=== "app.py"
```{.python pycafe-link}
import pandas as pd
@@ -258,8 +234,8 @@ possible with the built-in functions then you can create a [custom figure](custo
value_column: Actual
reference_column: Reference
title: KPI reference with formatting
- value_format: "{value:.2f}€"
- reference_format: "{delta:+.2f}€ vs. last year ({reference:.2f}€)"
+ value_format: '{value:.2f}€'
+ reference_format: '{delta:+.2f}€ vs. last year ({reference:.2f}€)'
type: figure
- figure:
_target_: kpi_card_reference
@@ -276,7 +252,9 @@ possible with the built-in functions then you can create a [custom figure](custo
grid: [[0, 1, 2, 3], [4, 5, 6, 7], [-1, -1, -1, -1], [-1, -1, -1, -1]]
title: KPI cards
```
+
=== "Result"
- [![KPICards]][KPICards]
+ [![KPICards]][kpicards]
- [KPICards]: ../../assets/user_guides/figure/kpi_cards.png
+[figure]: ../../assets/user_guides/figure/figure.png
+[kpicards]: ../../assets/user_guides/figure/kpi_cards.png
diff --git a/vizro-core/docs/pages/user-guides/filters.md b/vizro-core/docs/pages/user-guides/filters.md
index bc3649178..8228ecbe7 100644
--- a/vizro-core/docs/pages/user-guides/filters.md
+++ b/vizro-core/docs/pages/user-guides/filters.md
@@ -2,8 +2,7 @@
This guide shows you how to add filters to your dashboard. One main way to interact with the charts/components on your page is by filtering the underlying data. A filter selects a subset of rows of a component's underlying DataFrame which alters the appearance of that component on the page.
-The [`Page`][vizro.models.Page] model accepts the `controls` argument, where you can enter a [`Filter`][vizro.models.Filter] model.
-This model enables the automatic creation of [selectors](selectors.md) (for example, `Dropdown` or `RangeSlider`) that operate on the charts/components on the screen.
+The [`Page`][vizro.models.Page] model accepts the `controls` argument, where you can enter a [`Filter`][vizro.models.Filter] model. This model enables the automatic creation of [selectors](selectors.md) (for example, `Dropdown` or `RangeSlider`) that operate on the charts/components on the screen.
By default, filters that control components with [dynamic data](data.md#dynamic-data) are [dynamically updated](data.md#filters) when the underlying data changes while the dashboard is running.
@@ -12,7 +11,7 @@ By default, filters that control components with [dynamic data](data.md#dynamic-
To add a filter to your page, do the following:
1. add the [`Filter`][vizro.models.Filter] model into the `controls` argument of the [`Page`][vizro.models.Page] model
-2. configure the `column` argument, which denotes the target column to be filtered
+1. configure the `column` argument, which denotes the target column to be filtered
You can also set `targets` to specify which components on the page the filter should apply to. If this is not explicitly set then `targets` defaults to all components on the page whose data source includes `column`.
@@ -39,6 +38,7 @@ You can also set `targets` to specify which components on the page the filter sh
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -57,17 +57,15 @@ You can also set `targets` to specify which components on the page the filter sh
type: filter
title: My first page
```
- === "Result"
- [![Filter]][Filter]
-
- [Filter]: ../../assets/user_guides/control/control1.png
+ === "Result"
+ [![Filter]][filter]
The selector is configured automatically based on the target column type data as follows:
- - Categorical data uses [`vm.Dropdown(multi=True)`][vizro.models.Dropdown] where `options` is the set of unique values found in `column` across all the data sources of components in `targets`.
- - [Numerical data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_numeric_dtype.html) uses [`vm.RangeSlider`][vizro.models.RangeSlider] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`.
- - [Temporal data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_datetime64_any_dtype.html) uses [`vm.DatePicker(range=True)`][vizro.models.DatePicker] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`. A column can be converted to this type with [pandas.to_datetime](https://pandas.pydata.org/docs/reference/api/pandas.to_datetime.html).
+- Categorical data uses [`vm.Dropdown(multi=True)`][vizro.models.Dropdown] where `options` is the set of unique values found in `column` across all the data sources of components in `targets`.
+- [Numerical data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_numeric_dtype.html) uses [`vm.RangeSlider`][vizro.models.RangeSlider] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`.
+- [Temporal data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_datetime64_any_dtype.html) uses [`vm.DatePicker(range=True)`][vizro.models.DatePicker] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`. A column can be converted to this type with [pandas.to_datetime](https://pandas.pydata.org/docs/reference/api/pandas.to_datetime.html).
The following example demonstrates these default selector types.
@@ -107,6 +105,7 @@ The following example demonstrates these default selector types.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -129,15 +128,13 @@ The following example demonstrates these default selector types.
type: filter
title: My first page
```
- === "Result"
- [![Filter]][Filter]
- [Filter]: ../../assets/user_guides/selectors/default_filter_selectors.png
+ === "Result"
+ [![Filter]][filter]
## Change selector
-If you want to have a different selector for your filter, you can give the `selector` argument of the [`Filter`][vizro.models.Filter] a different selector model.
-Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropdown`][vizro.models.Dropdown], [`RadioItems`][vizro.models.RadioItems], [`RangeSlider`][vizro.models.RangeSlider], [`Slider`][vizro.models.Slider], and [`DatePicker`][vizro.models.DatePicker].
+If you want to have a different selector for your filter, you can give the `selector` argument of the [`Filter`][vizro.models.Filter] a different selector model. Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropdown`][vizro.models.Dropdown], [`RadioItems`][vizro.models.RadioItems], [`RangeSlider`][vizro.models.RangeSlider], [`Slider`][vizro.models.Slider], and [`DatePicker`][vizro.models.DatePicker].
!!! example "Filter with different selector"
=== "app.py"
@@ -162,6 +159,7 @@ Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropd
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -181,11 +179,9 @@ Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropd
type: filter
title: My first page
```
- === "Result"
-
- [![Selector]][Selector]
- [Selector]: ../../assets/user_guides/control/control2.png
+ === "Result"
+ [![Selector]][selector]
## Further customization
@@ -220,6 +216,7 @@ Below is an advanced example where we only target one page component, and where
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -244,17 +241,19 @@ Below is an advanced example where we only target one page component, and where
controls:
- column: petal_length
targets:
- - scatter_chart
+ - scatter_chart
selector:
step: 1
type: range_slider
type: filter
title: My first page
```
- === "Result"
-
- [![Advanced]][Advanced]
- [Advanced]: ../../assets/user_guides/control/control3.png
+ === "Result"
+ [![Advanced]][advanced]
To further customize selectors, see our [how-to-guide on creating custom components](custom-components.md).
+
+[advanced]: ../../assets/user_guides/control/control3.png
+[filter]: ../../assets/user_guides/control/control1.png
+[selector]: ../../assets/user_guides/control/control2.png
diff --git a/vizro-core/docs/pages/user-guides/graph.md b/vizro-core/docs/pages/user-guides/graph.md
index 36c670997..1c3ffc8bc 100755
--- a/vizro-core/docs/pages/user-guides/graph.md
+++ b/vizro-core/docs/pages/user-guides/graph.md
@@ -6,25 +6,18 @@ The [`Graph`][vizro.models.Graph] model is the most used component in many dashb
To add a [`Graph`][vizro.models.Graph] to your page, do the following:
-1. insert the [`Graph`][vizro.models.Graph] model into the `components` argument of the
-[`Page`][vizro.models.Page] model
-2. enter any of the currently available charts of the open source library [`plotly.express`](https://plotly.com/python/plotly-express/) into the `figure` argument
+1. insert the [`Graph`][vizro.models.Graph] model into the `components` argument of the [`Page`][vizro.models.Page] model
+1. enter any of the currently available charts of the open source library [`plotly.express`](https://plotly.com/python/plotly-express/) into the `figure` argument
!!! note
+ To use the [`plotly.express`](https://plotly.com/python/plotly-express/) chart in a Vizro dashboard, you need to import it as `import vizro.plotly.express as px`. This leaves any of the [`plotly.express`](https://plotly.com/python/plotly-express/) functionality untouched yet enables _direct insertion_ into the [`Graph`][vizro.models.Graph] model _as is_.
- In order to use the [`plotly.express`](https://plotly.com/python/plotly-express/) chart in a Vizro dashboard, you need to import it as `import vizro.plotly.express as px`.
- This leaves any of the [`plotly.express`](https://plotly.com/python/plotly-express/) functionality untouched, but allows _direct insertion_ into the [`Graph`][vizro.models.Graph] model _as is_.
-
- Note also that the `plotly.express` chart needs to have a `data_frame` argument. In case you require a chart without
- a `data_frame` argument (for example, the [`imshow` chart](https://plotly.com/python/imshow/)), refer to our
- [guide on custom charts](custom-charts.md).
-
+ Note also that the `plotly.express` chart needs to have a `data_frame` argument. In case you require a chart without a `data_frame` argument (for example, the [`imshow` chart](https://plotly.com/python/imshow/)), refer to our [guide on custom charts](custom-charts.md).
## Insert Plotly chart
!!! example "Graph"
=== "app.py"
-
```{.python pycafe-link}
import vizro.models as vm
import vizro.plotly.express as px
@@ -47,25 +40,24 @@ To add a [`Graph`][vizro.models.Graph] to your page, do the following:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: scatter_matrix
- color: species
- data_frame: iris
- dimensions: ["sepal_length", "sepal_width", "petal_length", "petal_width"]
- type: graph
- title: My first page
+ - components:
+ - figure:
+ _target_: scatter_matrix
+ color: species
+ data_frame: iris
+ dimensions: [sepal_length, sepal_width, petal_length, petal_width]
+ type: graph
+ title: My first page
```
- === "Result"
- [![Graph]][Graph]
-
- [Graph]: ../../assets/user_guides/components/graph.png
+ === "Result"
+ [![Graph]][graph]
In the Python example we directly inserted the pandas DataFrame `df` into `figure=px.scatter_matrix(df, ...)`. This is [one way to supply data to a chart](data.md#supply-directly). For the YAML version, we [refer to the data source by name](data.md#reference-by-name) as `data_frame: iris`. For a full explanation of the different methods you can use to send data to your dashboard, see [our guide to using data in Vizro](data.md).
@@ -73,31 +65,24 @@ In the Python example we directly inserted the pandas DataFrame `df` into `figur
You will need to create a custom chart if you want to customize the Plotly chart beyond a function call, for example by:
-* using post-update methods like `update_layout`, `update_xaxes`, `update_traces`, or
-* by creating a custom `plotly.graph_objects.Figure()` object and manually adding traces with `add_trace`.
-
-For more details, refer to our [user guide on custom chart](custom-charts.md) and the
-[Plotly documentation on updating figures](https://plotly.com/python/creating-and-updating-figures/).
+- using post-update methods like `update_layout`, `update_xaxes`, `update_traces`, or
+- by creating a custom `plotly.graph_objects.Figure()` object and manually adding traces with `add_trace`.
+For more details, refer to our [user guide on custom chart](custom-charts.md) and the [Plotly documentation on updating figures](https://plotly.com/python/creating-and-updating-figures/).
## Add title, header, and footer
-The [`Graph`][vizro.models.Graph] accepts a `title`, `header` and `footer` argument. This is useful for providing
-context to the data being displayed, or for adding a description of the data.
+The [`Graph`][vizro.models.Graph] accepts a `title`, `header` and `footer` argument. This is useful for context on the data being displayed, or for adding a description of the data.
- **title**: Displayed as an [H3 header](https://dash.plotly.com/dash-html-components/h3), useful for summarizing the main topic or insight of the component.
- **header**: Accepts markdown text, ideal for extra descriptions, subtitles, or detailed data insights.
- **footer**: Accepts markdown text, commonly used for citing data sources, providing information on the last update, or adding disclaimers.
-
!!! note
-
- Although you can directly provide a `title` to the Plotly Express chart, we recommend using `Graph.title` for
- proper alignment with other components on the screen.
+ Although you can directly give a `title` to the Plotly Express chart, we recommend using `Graph.title` for proper alignment with other components on the screen.
!!! example "Formatted Graph"
=== "app.py"
-
```{.python pycafe-link}
import vizro.models as vm
@@ -126,31 +111,34 @@ context to the data being displayed, or for adding a description of the data.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: scatter
- x: sepal_width
- y: sepal_length
- color: species
- data_frame: iris
- title: Relationships between Sepal Width and Sepal Length
- header: |
- Each point in the scatter plot represents one of the 150 iris flowers, with colors indicating their
- types. The Setosa type is easily identifiable by its short and wide sepals.
-
- However, there is still overlap between the Versicolor and Virginica types when considering only sepal
- width and length.
- footer: |
- SOURCE: **Plotly iris data set, 2024**
- type: graph
- title: Formatted Graph
+ - components:
+ - figure:
+ _target_: scatter
+ x: sepal_width
+ y: sepal_length
+ color: species
+ data_frame: iris
+ title: Relationships between Sepal Width and Sepal Length
+ header: |
+ Each point in the scatter plot represents one of the 150 iris flowers, with colors indicating their
+ types. The Setosa type is easily identifiable by its short and wide sepals.
+
+ However, there is still overlap between the Versicolor and Virginica types when considering only sepal
+ width and length.
+ footer: |
+ SOURCE: **Plotly iris data set, 2024**
+ type: graph
+ title: Formatted Graph
```
+
=== "Result"
- [![FormattedGraph]][FormattedGraph]
+ [![FormattedGraph]][formattedgraph]
- [FormattedGraph]: ../../assets/user_guides/components/formatted_graph.png
+[formattedgraph]: ../../assets/user_guides/components/formatted_graph.png
+[graph]: ../../assets/user_guides/components/graph.png
diff --git a/vizro-core/docs/pages/user-guides/install.md b/vizro-core/docs/pages/user-guides/install.md
index 4d4c01239..6a07911e5 100644
--- a/vizro-core/docs/pages/user-guides/install.md
+++ b/vizro-core/docs/pages/user-guides/install.md
@@ -8,8 +8,8 @@ We recommend that you create a virtual environment for each Vizro project you wo
## Prerequisites to working locally
-* **Python**: Vizro supports macOS, Linux, and Windows. It works with Python 3.9 and later.
-* **Virtual environment**: You specify the version of Python to use with Vizro when you set up the virtual environment. See the following references to learn more about [Python virtual environments](https://realpython.com/python-virtual-environments-a-primer/), [Conda virtual environments](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#starting-conda) or [watch an explainer video about them](https://youtu.be/YKfAwIItO7M).
+- **Python**: Vizro supports macOS, Linux, and Windows. It works with Python 3.9 and later.
+- **Virtual environment**: You specify the version of Python to use with Vizro when you set up the virtual environment. See the following references to learn more about [Python virtual environments](https://realpython.com/python-virtual-environments-a-primer/), [Conda virtual environments](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#starting-conda) or [watch an explainer video about them](https://youtu.be/YKfAwIItO7M).
### How to create a virtual environment for your Vizro project
diff --git a/vizro-core/docs/pages/user-guides/kedro-data-catalog.md b/vizro-core/docs/pages/user-guides/kedro-data-catalog.md
index 0e2b0954e..ce4b060fa 100644
--- a/vizro-core/docs/pages/user-guides/kedro-data-catalog.md
+++ b/vizro-core/docs/pages/user-guides/kedro-data-catalog.md
@@ -3,6 +3,7 @@
This page describes how to integrate Vizro with [Kedro](https://docs.kedro.org/en/stable/index.html), an open-source Python framework to create reproducible, maintainable, and modular data science code. For Pandas datasets registered in a Kedro data catalog, Vizro provides a convenient way to visualize them.
## Installation
+
If you already have Kedro installed then you do not need to install any extra dependencies. If you do not have Kedro installed then you should run:
```bash
@@ -10,7 +11,9 @@ pip install vizro[kedro]
```
## Use datasets from the Kedro Data Catalog
+
`vizro.integrations.kedro` provides functions to help generate and process a [Kedro Data Catalog](https://docs.kedro.org/en/stable/data/index.html). Given a Kedro Data Catalog `catalog`, the general pattern to add datasets into the Vizro data manager is:
+
```python
from vizro.integrations import kedro as kedro_integration
from vizro.managers import data_manager
@@ -25,15 +28,14 @@ This imports all datasets of type [`kedro_datasets.pandas`](https://docs.kedro.o
The `catalog` variable may have been created in a number of different ways:
1. Kedro project path. Vizro exposes a helper function `vizro.integrations.kedro.catalog_from_project` to generate a `catalog` given the path to a Kedro project.
-2. [Kedro Jupyter session](https://docs.kedro.org/en/stable/notebooks_and_ipython/kedro_and_notebooks.html). This automatically exposes `catalog`.
-3. Data Catalog configuration file (`catalog.yaml`). This can create a `catalog` entirely independently of a Kedro project using [`kedro.io.DataCatalog.from_config`](https://docs.kedro.org/en/stable/kedro.io.DataCatalog.html#kedro.io.DataCatalog.from_config).
+1. [Kedro Jupyter session](https://docs.kedro.org/en/stable/notebooks_and_ipython/kedro_and_notebooks.html). This automatically exposes `catalog`.
+1. Data Catalog configuration file (`catalog.yaml`). This can create a `catalog` entirely independently of a Kedro project using [`kedro.io.DataCatalog.from_config`](https://docs.kedro.org/en/stable/kedro.io.DataCatalog.html#kedro.io.DataCatalog.from_config).
The full code for these different cases is given below.
!!! example "Import a Kedro Data Catalog into the Vizro data manager"
-
=== "app.py (Kedro project path)"
- ```py
+ ```python
from vizro.integrations import kedro as kedro_integration
from vizro.managers import data_manager
@@ -43,16 +45,18 @@ The full code for these different cases is given below.
for dataset_name, dataset in kedro_integration.datasets_from_catalog(catalog).items():
data_manager[dataset_name] = dataset
```
+
=== "app.ipynb (Kedro Jupyter session)"
- ```py
+ ```python
from vizro.managers import data_manager
for dataset_name, dataset in kedro_integration.datasets_from_catalog(catalog).items():
data_manager[dataset_name] = dataset
```
+
=== "app.py (Data Catalog configuration file)"
- ```py
+ ```python
from kedro.io import DataCatalog
import yaml
diff --git a/vizro-core/docs/pages/user-guides/layouts.md b/vizro-core/docs/pages/user-guides/layouts.md
index 8361560db..af66ec301 100644
--- a/vizro-core/docs/pages/user-guides/layouts.md
+++ b/vizro-core/docs/pages/user-guides/layouts.md
@@ -3,11 +3,10 @@
The [`Page`][vizro.models.Page] model accepts a `layout` argument that enables custom arrangement of charts and components on the screen. This guide shows how to customize the grid specifications in the [`Layout`][vizro.models.Layout].
## The default layout
-The `layout` argument of the [`Page`][vizro.models.Page] model is optional. If no layout is specified, all charts/components are automatically [**stacked vertically**](layouts.md#vertical-and-horizontal-stacking) on the page in one column.
-If you are happy with that arrangement, you can create your charts/components without providing a [`Layout`][vizro.models.Layout].
-!!! example "Default Layout"
+The `layout` argument of the [`Page`][vizro.models.Page] model is optional. If no layout is specified, all charts/components are automatically [**stacked vertically**](layouts.md#vertical-and-horizontal-stacking) on the page in one column. If you are happy with that arrangement, you can create your charts/components without providing a [`Layout`][vizro.models.Layout].
+!!! example "Default Layout"
=== "app.py"
```{.python pycafe-link}
from vizro import Vizro
@@ -23,35 +22,33 @@ If you are happy with that arrangement, you can create your charts/components wi
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- title: two_left
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ title: two_left
```
- === "Result"
- [![Layout]][Layout]
-
- [Layout]: ../../assets/user_guides/layout/two_left.png
-
+ === "Result"
+ [![Layout]][layout]
## Configure the grid
+
To customize the grid arrangement, configure the `grid` parameter of the [`Layout`][vizro.models.Layout] model.
The example below shows an example of a valid `grid`:
```python title="Basic example"
-grid = [[0, 1],
- [0, 2]]
+grid = [[0, 1], [0, 2]]
```
- The `grid` must be provided as `list[list[int]]` (for example, `grid = [[0, 1], [0, 2]]`).
@@ -64,16 +61,12 @@ grid = [[0, 1],
- The area spanned by a chart/component in the grid must be rectangular.
- The grid can be arbitrarily large, allowing arbitrarily granular control of the grid.
-
## Vertical and horizontal stacking
+
As described above, when no `Layout` is specified, components are presented **vertically** as a single-column stack. If you have three components, the default `Layout.grid` will be as follows, with three equally sized rows, each containing a component spanning the entire width:
```python title="Vertical stacking"
-grid = [
- [0],
- [1],
- [2]
- ]
+grid = [[0], [1], [2]]
```
To present components **horizontally** in one row:
@@ -89,8 +82,8 @@ This defines a single row that occupies the entire width and height, divided int
## Grid - basic example
-!!! example "Grid Arrangement - Basic Example"
+!!! example "Grid Arrangement - Basic Example"
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -109,39 +102,37 @@ This defines a single row that occupies the entire width and height, divided int
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- - text: |
- # Component 2
- type: card
- layout:
- grid: [[0, 1], [0, 2]]
- title: one_left_two_right
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ layout:
+ grid: [[0, 1], [0, 2]]
+ title: one_left_two_right
```
- === "Result"
- [![Grid]][Grid]
- [Grid]: ../../assets/user_guides/layout/one_left_two_right.png
+ === "Result"
+ [![Grid]][grid]
## Grid - advanced example
If you want to divide the grid into subgrids with finer control over these, you can use [`Containers`](container.md). See our section on [when to use `Containers` vs. `Page.layout`](container.md#when-to-use-containers) for more information.
-The `Layout` provides full control over the arrangement of top-level components within a page,
-allowing arbitrarily granular control of the grid by creating larger grids.
+The `Layout` provides full control over the arrangement of top-level components within a page, allowing arbitrarily granular control of the grid by creating larger grids.
!!! example "Grid Arrangement - Advanced Example"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -208,6 +199,7 @@ allowing arbitrarily granular control of the grid by creating larger grids.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -260,44 +252,44 @@ allowing arbitrarily granular control of the grid by creating larger grids.
grid: [[0, 1, 3, 4], [2, 2, 3, 4]]
title: Custom Layout - Advanced Example
```
- === "Result"
- [![GridAdv]][GridAdv]
- [GridAdv]: ../../assets/user_guides/layout/grid_advanced.png
+ === "Result"
+ [![GridAdv]][gridadv]
## Custom layout examples
+
Here is a reference table of example layouts:
+
one row with one component, second row with two components stacked horizontally
-| Layout needed | Grid | Code |
-|--------------------------------|----------------------------|-------------------------------------------------------------------------------------|
-| | | `layout=vm.Layout(grid=[[0]])` |
-| | | `layout=vm.Layout(grid=[[0],[1]])` |
-| | | `layout=vm.Layout(grid=[[0,1]])` |
-| | | `layout=vm.Layout(grid=[[0],[1],[2]])` or
`layout=None` |
-| | | `layout=vm.Layout(grid=[[0,1],[0,2]])` |
-| | | `layout=vm.Layout(grid=[[0,0],[1,2]])` |
-| | | `layout=vm.Layout(grid=[[0,1],[2,2]])` |
-| | | `layout=vm.Layout(grid=[[0,1],[0,2],[0,3]])` |
-| | | `layout=vm.Layout(grid=[[0,1],[2,3]])` |
-| | | `layout=vm.Layout(grid=[[0,3],[1,3],[2,3]])` |
-| | | `layout=vm.Layout(grid=[[0,0,0],[1,2,3]])` |
-| | | `layout=vm.Layout(grid=[[0,1,2],[3,3,3]])` |
+| Layout needed | Grid | Code |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| | | `layout=vm.Layout(grid=[[0]])` |
+| | | `layout=vm.Layout(grid=[[0],[1]])` |
+| | | `layout=vm.Layout(grid=[[0,1]])` |
+| | | `layout=vm.Layout(grid=[[0],[1],[2]])` or
`layout=None` |
+| | | `layout=vm.Layout(grid=[[0,1],[0,2]])` |
+| | | `layout=vm.Layout(grid=[[0,0],[1,2]])` |
+| | | `layout=vm.Layout(grid=[[0,1],[2,2]])` |
+| | | `layout=vm.Layout(grid=[[0,1],[0,2],[0,3]])` |
+| | | `layout=vm.Layout(grid=[[0,1],[2,3]])` |
+| | | `layout=vm.Layout(grid=[[0,3],[1,3],[2,3]])` |
+| | | `layout=vm.Layout(grid=[[0,0,0],[1,2,3]])` |
+| | | `layout=vm.Layout(grid=[[0,1,2],[3,3,3]])` |
## Add empty sections to the grid
+
One approach to organize the dashboard's layout involves integrating empty sections by specifying `-1` within the grid layout.
```python title="Example"
-grid = [[0, 1, -1],
- [0, 2, -1]]
+grid = [[0, 1, -1], [0, 2, -1]]
```
!!! example "Adding Empty Spaces"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -316,38 +308,38 @@ grid = [[0, 1, -1],
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- - text: |
- # Component 2
- type: card
- layout:
- grid: [[0, 1, -1], [0, 2, -1]]
- title: Adding empty spaces
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ layout:
+ grid: [[0, 1, -1], [0, 2, -1]]
+ title: Adding empty spaces
```
- === "Result"
- [![GridEmpty]][GridEmpty]
- [GridEmpty]: ../../assets/user_guides/layout/layout_empty_spaces.png
+ === "Result"
+ [![GridEmpty]][gridempty]
## Control the scroll behavior
+
By default, the grid fits all charts/components on the screen. This can lead to distortions such that the chart/component looks squashed. To control the scroll behavior, you can specify the following:
- `row_min_height`: Sets a chart/component's minimum height. Defaults to 0px.
- `col_min_width`: Sets a chart/component's minimum width. Defaults to 0px.
!!! example "Activate Scrolling"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -371,59 +363,63 @@ By default, the grid fits all charts/components on the screen. This can lead to
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- - text: |
- # Component 2
- type: card
- - text: |
- # Component 2
- type: card
- - text: |
- # Component 4
- type: card
- - text: |
- # Component 5
- type: card
- - text: |
- # Component 6
- type: card
- - text: |
- # Component 7
- type: card
- layout:
- grid: [[0], [1], [2], [3], [4], [5], [6], [7]]
- row_min_height: 240px
- title: Activate scrolling
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ - text: |
+ # Component 4
+ type: card
+ - text: |
+ # Component 5
+ type: card
+ - text: |
+ # Component 6
+ type: card
+ - text: |
+ # Component 7
+ type: card
+ layout:
+ grid: [[0], [1], [2], [3], [4], [5], [6], [7]]
+ row_min_height: 240px
+ title: Activate scrolling
```
- === "Result"
- [![GridScroll]][GridScroll]
-
- [GridScroll]: ../../assets/user_guides/layout/grid_scroll.png
+ === "Result"
+ [![GridScroll]][gridscroll]
## Further customization
-For further customization, such as changing the gap between row and column, refer to the
-documentation of the [`Layout`][vizro.models.Layout] model.
+
+For further customization, such as changing the gap between row and column, refer to the documentation of the [`Layout`][vizro.models.Layout] model.
## Alternative layout approaches
+
In general, any arbitrarily granular layout can already be achieved using [`Page.layout`](layouts.md) alone and is our recommended approach if you want to arrange components on a page with consistent row and/or column spacing.
!!! note "Alternative layout approaches: `Tabs` and `Containers`"
-
- [`Tabs`][vizro.models.Tabs] and [`Containers`][vizro.models.Container] provide an alternative approach to customize your page layout.
- For example, if you want to have more granular control and break the overall page grid into subgrids, see our [user guide on Containers](container.md).
+ [`Tabs`][vizro.models.Tabs] and [`Containers`][vizro.models.Container] offer an alternative approach to customize your page layout. For example, if you want to have more granular control and break the overall page grid into subgrids, see our [user guide on Containers](container.md).
If you want to display multiple containers on one page by putting them into the same screen space, and letting the user switch between them, see our [user guide on Tabs](tabs.md).
{ width="500" }
+
+[grid]: ../../assets/user_guides/layout/one_left_two_right.png
+[gridadv]: ../../assets/user_guides/layout/grid_advanced.png
+[gridempty]: ../../assets/user_guides/layout/layout_empty_spaces.png
+[gridscroll]: ../../assets/user_guides/layout/grid_scroll.png
+[layout]: ../../assets/user_guides/layout/two_left.png
diff --git a/vizro-core/docs/pages/user-guides/navigation.md b/vizro-core/docs/pages/user-guides/navigation.md
index 41c6bb9dc..75a661470 100644
--- a/vizro-core/docs/pages/user-guides/navigation.md
+++ b/vizro-core/docs/pages/user-guides/navigation.md
@@ -2,8 +2,7 @@
This guide shows you how to use and customize the navigation that appears on the left of your dashboard.
-The [`Dashboard`][vizro.models.Dashboard] model accepts a `navigation` argument, where you can enter a [`Navigation`][vizro.models.Navigation] model. This enables you to group pages together and customize how they appear in your navigation.
-The dashboard includes a collapsible side panel that users can minimize or expand by a button click. The collapse button, located in the top right corner of the side panel, is visible by default for user convenience.
+The [`Dashboard`][vizro.models.Dashboard] model accepts a `navigation` argument, where you can enter a [`Navigation`][vizro.models.Navigation] model. This enables you to group pages together and customize how they appear in your navigation. The dashboard includes a collapsible side panel that users can minimize or expand by a button click. The collapse button, located in the top right corner of the side panel, is visible by default for user convenience.
## Use the default navigation
@@ -56,8 +55,8 @@ By default, if the `navigation` argument is not specified, Vizro creates a navig
type: graph
title: My first page
- components:
- - text: My text here
- type: card
+ - text: My text here
+ type: card
title: My second page
- components:
- figure:
@@ -69,10 +68,9 @@ By default, if the `navigation` argument is not specified, Vizro creates a navig
type: graph
title: My third page
```
- === "Result"
- [![DefaultNavigation]][DefaultNavigation]
- [DefaultNavigation]: ../../assets/user_guides/navigation/default_navigation.png
+ === "Result"
+ [![DefaultNavigation]][defaultnavigation]
## Include a subset of pages
@@ -132,17 +130,15 @@ To include only some of your dashboard pages in your navigation then list them i
- My first page
- My second page
```
- === "Result"
- [![OnlySomePages]][OnlySomePages]
- [OnlySomePages]: ../../assets/user_guides/navigation/only_some_pages.png
+ === "Result"
+ [![OnlySomePages]][onlysomepages]
## Group pages
You can also group your pages together by specifying `pages` as a dictionary:
!!! example "Grouping pages"
-
=== "snippet.py"
```py
# page_1, page_2, page_3 defined as in default example
@@ -154,7 +150,6 @@ You can also group your pages together by specifying `pages` as a dictionary:
```
=== "app.py"
-
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -187,6 +182,7 @@ You can also group your pages together by specifying `pages` as a dictionary:
)
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -200,18 +196,15 @@ You can also group your pages together by specifying `pages` as a dictionary:
Group B:
- My third page
```
- === "Result"
- [![GroupedNavigation]][GroupedNavigation]
-
- [GroupedNavigation]: ../../assets/user_guides/navigation/grouped_navigation.png
+ === "Result"
+ [![GroupedNavigation]][groupednavigation]
## Use a navigation bar with icons
Another way to group together pages in the navigation is to use a [`NavBar`][vizro.models.NavBar] with icons. The simplest way to use this is to change the `nav_selector` specified in [`Navigation`][vizro.models.Navigation]:
!!! example "Using `NavBar`"
-
=== "snippet.py"
```py
# page_1, page_2, page_3 defined as in default example
@@ -223,8 +216,8 @@ Another way to group together pages in the navigation is to use a [`NavBar`][viz
)
Vizro().build(dashboard).run()
```
- === "app.py"
+ === "app.py"
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -276,14 +269,11 @@ Another way to group together pages in the navigation is to use a [`NavBar`][viz
nav_selector:
type: nav_bar
```
- === "Result"
- [![NavBar]][NavBar]
-
- [NavBar]: ../../assets/user_guides/navigation/nav_bar.png
+ === "Result"
+ [![NavBar]][navbar]
-Here, the first level of the navigation hierarchy ("Group A" and "Group B") is represented by an icon in a navigation bar, and the second level of the navigation (the pages) is represented by an accordion.
-By default, the set of icons used are the [`filter` icons from the Google Material icons library](https://fonts.google.com/icons?icon.query=filter). The icon label ("Group A" and "Group B") appears as a tooltip on hovering over the icon.
+Here, the first level of the navigation hierarchy ("Group A" and "Group B") is represented by an icon in a navigation bar, and the second level of the navigation (the pages) is represented by an accordion. By default, the set of icons used are the [`filter` icons from the Google Material icons library](https://fonts.google.com/icons?icon.query=filter). The icon label ("Group A" and "Group B") appears as a tooltip on hovering over the icon.
## Customize the navigation bar
@@ -314,7 +304,6 @@ The same configuration for [grouping pages](#group-pages) applies inside a `NavL
```
=== "app.py"
-
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -375,10 +364,9 @@ The same configuration for [grouping pages](#group-pages) applies inside a `NavL
Group B:
- My third page
```
- === "Result"
- [![AccordionInsideNavBar]][AccordionInsideNavBar]
- [AccordionInsideNavBar]: ../../assets/user_guides/navigation/accordion_inside_nav_bar.png
+ === "Result"
+ [![AccordionInsideNavBar]][accordioninsidenavbar]
You can alter the icons used by specifying the name of the icon in the [Google Material icons library](https://fonts.google.com/icons):
@@ -402,8 +390,8 @@ You can alter the icons used by specifying the name of the icon in the [Google M
),
)
```
- === "app.py"
+ === "app.py"
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -468,7 +456,13 @@ You can alter the icons used by specifying the name of the icon in the [Google M
pages:
- My third page
```
- === "Result"
- [![CustomIcons]][CustomIcons]
- [CustomIcons]: ../../assets/user_guides/navigation/custom_icons.png
+ === "Result"
+ [![CustomIcons]][customicons]
+
+[accordioninsidenavbar]: ../../assets/user_guides/navigation/accordion_inside_nav_bar.png
+[customicons]: ../../assets/user_guides/navigation/custom_icons.png
+[defaultnavigation]: ../../assets/user_guides/navigation/default_navigation.png
+[groupednavigation]: ../../assets/user_guides/navigation/grouped_navigation.png
+[navbar]: ../../assets/user_guides/navigation/nav_bar.png
+[onlysomepages]: ../../assets/user_guides/navigation/only_some_pages.png
diff --git a/vizro-core/docs/pages/user-guides/pages.md b/vizro-core/docs/pages/user-guides/pages.md
index 7ae944e9b..71e01e9f9 100644
--- a/vizro-core/docs/pages/user-guides/pages.md
+++ b/vizro-core/docs/pages/user-guides/pages.md
@@ -1,7 +1,6 @@
# How to use pages
-This guide shows you how to add pages to your dashboard and customize the URL paths if needed.
-A [`Page`][vizro.models.Page] lets you place and arrange your dashboard content (for example, chart/components, tables, and text)
-and configure your dashboard interactions (such as filters and parameters).
+
+This guide shows you how to add pages to your dashboard and customize the URL paths if needed. A [`Page`][vizro.models.Page] lets you place and arrange your dashboard content (for example, chart/components, tables, and text) and configure your dashboard interactions (such as filters and parameters).
The [`Dashboard`][vizro.models.Dashboard] model accepts the `pages` argument, where you can insert your [`Page`][vizro.models.Page].
@@ -10,19 +9,19 @@ The [`Dashboard`][vizro.models.Dashboard] model accepts the `pages` argument, wh
A [`Page`][vizro.models.Page] is split up into four main containers:
1. The **navigation container** where you can customize your `navigation` (see [Dashboard](dashboard.md) and [Navigation](navigation.md) for more information). Note that the navigation container needs to be configured via the Dashboard.
-2. The **control container** where you can add your `controls` (see [Filters](filters.md) or [Parameters](parameters.md)) to interact with the dashboard
-3. The **page header** that contains the page title and the theme toggle switch button
-4. The **component container** where you can add your [components](components.md) to visualize your data
+1. The **control container** where you can add your `controls` (see [Filters](filters.md) or [Parameters](parameters.md)) to interact with the dashboard
+1. The **page header** that contains the page title and the theme toggle switch button
+1. The **component container** where you can add your [components](components.md) to visualize your data
To create and add a page to your dashboard, do the following steps:
1. Set a `title` for your [`Page`][vizro.models.Page]
-2. Configure your `components`, see our guide on the [various options](components.md)
-3. (optional) Configure your `controls` , see our guides on [Filters](filters.md) and [Parameters](parameters.md)
-4. (optional) Configure your `layout` , see our guide on [Layouts](layouts.md)
-5. (optional) Give a `description` of your `Page` to the app's [meta tags](https://metatags.io/)
+1. Configure your `components`, see our guide on the [various options](components.md)
+1. (optional) Configure your `controls` , see our guides on [Filters](filters.md) and [Parameters](parameters.md)
+1. (optional) Configure your `layout` , see our guide on [Layouts](layouts.md)
+1. (optional) Give a `description` of your `Page` to the app's [meta tags](https://metatags.io/)
!!! example "Page"
=== "app.py"
@@ -51,51 +50,47 @@ To create and add a page to your dashboard, do the following steps:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: sunburst
- path: ['continent', 'country']
- values: pop
- color: lifeExp
- data_frame: gapminder
- id: sunburst
- type: graph
- controls:
- - column: continent
- targets:
- - sunburst
- type: filter
- - selector:
- options: ['lifeExp', 'pop']
- title: Color
- type: radio_items
- targets:
- - sunburst.color
- type: parameter
- title: Page Title
- description: "Longer description of the page content"
+ - components:
+ - figure:
+ _target_: sunburst
+ path: [continent, country]
+ values: pop
+ color: lifeExp
+ data_frame: gapminder
+ id: sunburst
+ type: graph
+ controls:
+ - column: continent
+ targets: [sunburst]
+ type: filter
+ - selector:
+ options: [lifeExp, pop]
+ title: Color
+ type: radio_items
+ targets: [sunburst.color]
+ type: parameter
+ title: Page Title
+ description: Longer description of the page content
```
- === "Result"
- [![Page]][Page]
- [Page]: ../../assets/user_guides/pages/page_sunburst.png
+ === "Result"
+ [![Page]][page]
An accordion page selector is automatically added to your dashboard in the top-left of the control container for through the different pages. It will not be added if your dashboard consists of only one page.
You can additionally navigate through the different pages by going directly to the relevant page URL (more details in next section).
-
## Customize the page URL
-By default, the page URL is automatically generated based on the `id` of the page. For example, if `id="This is my first page"`
-the generated page URL will be `path=this-is-my-first-page`. You can then access the page via `localhost:/this-is-my-first-page`.
-Note that the page `id` defaults to be the same as the page `title` if not set.
-If you have multiple pages with the same `title` then you must assign a unique `id`.
+By default, the page URL is automatically generated based on the `id` of the page. For example, if `id="This is my first page"` the generated page URL will be `path=this-is-my-first-page`. You can then access the page via `localhost:/this-is-my-first-page`.
+
+Note that the page `id` defaults to be the same as the page `title` if not set. If you have multiple pages with the same `title` then you must assign a unique `id`.
The first page always has the URL prefix `/` assigned. A custom URL can, therefore, not be created for the first page.
@@ -137,39 +132,40 @@ To customize the page URL, pass a valid URL name to the `path` argument of [`Pag
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- Commodi repudiandae consequuntur voluptatum.
- type: card
- title: Page 1
- - components:
- - figure:
- _target_: sunburst
- path: ['continent', 'country']
- values: pop
- color: lifeExp
- data_frame: gapminder
- id: sunburst
- type: graph
- controls:
- - column: continent
- targets:
- - sunburst
- type: filter
- - selector:
- options: ['lifeExp', 'pop']
- title: Color
- type: radio_items
- targets:
- - sunburst.color
- type: parameter
- title: Page 2
- path: my-custom-url
+ - components:
+ - text: |
+ Commodi repudiandae consequuntur voluptatum.
+ type: card
+ title: Page 1
+ - components:
+ - figure:
+ _target_: sunburst
+ path: [continent, country]
+ values: pop
+ color: lifeExp
+ data_frame: gapminder
+ id: sunburst
+ type: graph
+ controls:
+ - column: continent
+ targets: [sunburst]
+ type: filter
+ - selector:
+ options: [lifeExp, pop]
+ title: Color
+ type: radio_items
+ targets: [sunburst.color]
+ type: parameter
+ title: Page 2
+ path: my-custom-url
```
You can now access the first page via `localhost:/` and the second page via `localhost:/my-custom-url`.
+
+[page]: ../../assets/user_guides/pages/page_sunburst.png
diff --git a/vizro-core/docs/pages/user-guides/parameters.md b/vizro-core/docs/pages/user-guides/parameters.md
index bb39a7a0c..c82707d4a 100644
--- a/vizro-core/docs/pages/user-guides/parameters.md
+++ b/vizro-core/docs/pages/user-guides/parameters.md
@@ -9,8 +9,8 @@ The [`Page`][vizro.models.Page] model accepts the `controls` argument, where you
To add a parameter to your page, do the following:
1. add the [`Parameter`][vizro.models.Parameter] model into the `controls` argument of the [`Page`][vizro.models.Page] model.
-2. add the `targets` argument
-3. add a selector model to the `selector` argument.
+1. add the `targets` argument
+1. add a selector model to the `selector` argument.
In the `targets` argument, you can specify the component and function argument that the parameter should be applied to in the form of `.` (for example, `scatter_chart.title`).
@@ -48,6 +48,7 @@ Unlike for the [`Filter`][vizro.models.Filter] model, you also have to configure
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -64,18 +65,17 @@ Unlike for the [`Filter`][vizro.models.Filter] model, you also have to configure
type: graph
controls:
- selector:
- options: ["My scatter chart", "A better title!", "Another title..."]
- multi: False
+ options: [My scatter chart, A better title!, Another title...]
+ multi: false
type: dropdown
targets:
- scatter_chart.title
type: parameter
title: My first page
```
- === "Result"
- [![Parameter]][Parameter]
- [Parameter]: ../../assets/user_guides/control/control4.png
+ === "Result"
+ [![Parameter]][parameter]
If you would like to pass `None` as a parameter and make a parameter optional, you can specify the string `"NONE"` in the `options` or `value` field.
@@ -133,6 +133,7 @@ If you want to change nested parameters, you can specify the `targets` argument
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -146,7 +147,7 @@ If you want to change nested parameters, you can specify the `targets` argument
y: sepal_length
size: petal_length
color: species
- color_discrete_map: {"setosa": "#00b4ff", "versicolor": "#ff9222"}
+ color_discrete_map: {setosa: '#00b4ff', versicolor: '#ff9222'}
id: scatter_chart
type: graph
- figure:
@@ -155,23 +156,22 @@ If you want to change nested parameters, you can specify the `targets` argument
x: sepal_width
y: sepal_length
color: species
- color_discrete_map: {"setosa": "#00b4ff", "versicolor": "#ff9222"}
+ color_discrete_map: {setosa: '#00b4ff', versicolor: '#ff9222'}
id: bar_chart
type: graph
controls:
- selector:
- options: ["#ff5267", "#3949ab"]
+ options: ['#ff5267', '#3949ab']
value: #3949ab
- multi: False
+ multi: false
type: dropdown
- targets: ["scatter_chart.color_discrete_map.virginica", "bar_chart.color_discrete_map.virginica"]
+ targets: [scatter_chart.color_discrete_map.virginica, bar_chart.color_discrete_map.virginica]
type: parameter
title: My first page
```
- === "Result"
- [![Nested]][Nested]
- [Nested]: ../../assets/user_guides/control/control5.png
+ === "Result"
+ [![Nested]][nested]
In the above example, the object passed to the function argument `color_discrete_map` is a dictionary which maps the different flower species to fixed colors (for example, `{"virginica":"blue"}`). In this case, only the value `blue` should be changed instead of the entire dictionary. This can be achieved by specifying a target as `scatter.color_discrete_map.virginica`.
@@ -180,3 +180,6 @@ Note that in the above example, one parameter affects multiple targets.
## Dynamic data parameters
If you use [dynamic data](data.md/#dynamic-data) that can be updated while the dashboard is running then you can pass parameters to the dynamic data function to alter the data loaded into your dashboard. For detailed instructions, refer to the section on [parametrized data loading](data.md/#parametrize-data-loading).
+
+[nested]: ../../assets/user_guides/control/control5.png
+[parameter]: ../../assets/user_guides/control/control4.png
diff --git a/vizro-core/docs/pages/user-guides/run.md b/vizro-core/docs/pages/user-guides/run.md
index df52e8c14..028eb5027 100644
--- a/vizro-core/docs/pages/user-guides/run.md
+++ b/vizro-core/docs/pages/user-guides/run.md
@@ -15,7 +15,6 @@ Most of our examples have a link below the code, [Run and edit this code in PyCa
You can use [PyCafe](https://py.cafe/snippet/vizro/v1) snippet mode to experiment with your own Vizro dashboards by dropping code into a new project.
-
## Default built-in Flask development server
!!! example "Default built-in Flask development server"
@@ -38,9 +37,10 @@ You can use [PyCafe](https://py.cafe/snippet/vizro/v1) snippet mode to experimen
Vizro().build(dashboard).run()
```
+
1. create a Python file named `app.py`.
-2. type the command `python app.py` into your terminal.
-3. information below will be displayed in your terminal, go to [http://127.0.0.1:8050/](http://127.0.0.1:8050/).
+1. type the command `python app.py` into your terminal.
+1. information below will be displayed in your terminal, go to [http://127.0.0.1:8050/](http://127.0.0.1:8050/).
```
Dash is running on http://127.0.0.1:8050/
@@ -51,8 +51,7 @@ INFO:werkzeug:WARNING: This is a development server. Do not use it in a producti
```
!!! warning "In production"
-
- As per the above warning message, which is [further explained in the Flask documentation](https://flask.palletsprojects.com/en/3.0.x/deploying/), the Flask development server is intended for use only during local development and **should not** be used when deploying to production. Instead, you should instead use a production-ready solution such as [Gunicorn](#gunicorn).
+ The above warning message is [further explained in the Flask documentation](https://flask.palletsprojects.com/en/3.0.x/deploying/). The Flask development server is intended for use only during local development and **should not** be used when deploying to production. Instead, you should instead use a production-ready solution such as [Gunicorn](#gunicorn).
### Automatic reloading and debugging
@@ -64,11 +63,11 @@ Setting `debug=True` enables [Dash Dev Tools](https://dash.plotly.com/devtools).
In addition, some errors generated at run time can also be viewed via the browser console (for example in `Chrome` see `View > Developer > Developer Tools > Console`).
-
## Jupyter
+
The dashboard application can be launched in a Jupyter environment in `inline`, `external`, and `jupyterlab` mode.
-!!! example "Run in a Jupyter Notebook in inline mode"
+!!! example "Run in a Jupyter Notebook in inline mode"
=== "app.ipynb"
```py linenums="1"
from vizro import Vizro
@@ -87,16 +86,16 @@ The dashboard application can be launched in a Jupyter environment in `inline`,
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run(jupyter_mode="external")
```
+
- by default, the mode is set to `inline` in `run()` and the dashboard will be displayed inside your Jupyter environment.
- you can specify `jupyter_mode="external"` and a link will be displayed to direct you to the localhost where the dashboard is running.
- you can use tab mode by `jupyter_mode="tab"` to automatically open the app in a new browser
!!! note "Reloading and debugging"
-
Code reloading and hot reloading do not work within a Jupyter Notebook. Instead, there are two methods to reload the dashboard:
- * Restart the Jupyter kernel and re-run your notebook.
- * Add a cell containing `from vizro import Vizro; Vizro._reset()` to the top of your notebook and re-run it. With this method, there is no need to restart the Jupyter kernel.
+ - Restart the Jupyter kernel and re-run your notebook.
+ - Add a cell containing `from vizro import Vizro; Vizro._reset()` to the top of your notebook and re-run it. With this method, there is no need to restart the Jupyter kernel.
## Gunicorn
@@ -126,17 +125,18 @@ The dashboard application can be launched in a Jupyter environment in `inline`,
```
1. The Vizro `app` object is a WSGI application that exposes the underlying Flask app; this will be used by Gunicorn.
- 2. Enable the same app to still be run using the built-in Flask server with `python app.py` for development purposes.
+ 1. Enable the same app to still be run using the built-in Flask server with `python app.py` for development purposes.
To run using Gunicorn with four worker processes, execute
+
```bash
gunicorn app:app --workers 4
```
+
in the command line. For more Gunicorn configuration options, refer to [Gunicorn documentation](https://docs.gunicorn.org/).
!!! warning "In production"
-
- If your dashboard uses [dynamic data](data.md#dynamic-data) that can be refreshed while the dashboard is running then you should [configure your data manager cache](data.md#configure-cache) to use a backend that supports multiple processes.
+ If your dashboard uses [dynamic data](data.md#dynamic-data) that can be refreshed while the dashboard is running then you should [configure your data manager cache](data.md#configure-cache) to use a back end that supports multiple processes.
## Deployment
@@ -149,6 +149,6 @@ Internally, `app = Vizro()` contains a Flask app in `app.dash.server`. However,
[`Vizro`][vizro.Vizro] accepts `**kwargs` that are passed through to `Dash`. This enables you to configure the underlying Dash app using the same [arguments that are available](https://dash.plotly.com/reference#dash.dash) in `Dash`. For example, in a deployment context, these arguments may be useful:
-- `url_base_pathname`: serve your Vizro app at a specific path rather than at the domain root. For example, if you host your dashboard at http://www.example.com/my_dashboard/ then you would set `url_base_pathname="/my_dashboard/"` or an environment variable `DASH_URL_BASE_PATHNAME="/my_dashboard/"`.
+- `url_base_pathname`: serve your Vizro app at a specific path rather than at the domain root. For example, if you host your dashboard at `http://www.example.com/my_dashboard/` then you would set `url_base_pathname="/my_dashboard/"` or an environment variable `DASH_URL_BASE_PATHNAME="/my_dashboard/"`.
- `serve_locally`: set to `False` to [serve Dash component libraries from a Content Delivery Network (CDN)](https://dash.plotly.com/external-resources#serving-dash's-component-libraries-locally-or-from-a-cdn), which reduces load on the server and can improve performance. Vizro uses [jsDeliver](https://www.jsdelivr.com/) as a CDN for CSS and JavaScript sources.
- `assets_external_path`: when `serve_locally=False`, you can also set `assets_external_path` or an environment variable `DASH_ASSETS_EXTERNAL_PATH` to [serve your own assets from a CDN](https://dash.plotly.com/external-resources#load-assets-from-a-folder-hosted-on-a-cdn).
diff --git a/vizro-core/docs/pages/user-guides/selectors.md b/vizro-core/docs/pages/user-guides/selectors.md
index 10481d2ba..a1bd4be20 100644
--- a/vizro-core/docs/pages/user-guides/selectors.md
+++ b/vizro-core/docs/pages/user-guides/selectors.md
@@ -6,10 +6,7 @@ The [`Filter`][vizro.models.Filter] or the [`Parameter`][vizro.models.Parameter]
## Categorical selectors
-Within the categorical selectors, a clear distinction exists between multi-option and single-option selectors.
-For instance, the [`Checklist`][vizro.models.Checklist] functions as a multi-option selector by default while
-the [`RadioItem`][vizro.models.RadioItems] serves as a single-option selector by default. However, the
-[`Dropdown`][vizro.models.Dropdown] can function as both a multi-option or single-option selector.
+Within the categorical selectors, a clear distinction exists between multi-option and single-option selectors. For instance, the [`Checklist`][vizro.models.Checklist] functions as a multi-option selector by default while the [`RadioItem`][vizro.models.RadioItems] serves as a single-option selector by default. However, the [`Dropdown`][vizro.models.Dropdown] can function as both a multi-option or single-option selector.
For more information, refer to the API reference of the selector, or the documentation of its underlying Dash component:
@@ -18,15 +15,12 @@ For more information, refer to the API reference of the selector, or the documen
- [`RadioItems`][vizro.models.RadioItems] based on [`dcc.RadioItems`](https://dash.plotly.com/dash-core-components/radioitems)
!!! note
-
- When configuring the `options` of the categorical selectors, you can either provide:
+ When configuring the `options` of the categorical selectors, you can either give:
- a list of values `options = ['Value A', 'Value B', 'Value C']`
- or a dictionary of label-value mappings `options=[{'label': 'True', 'value': True}, {'label': 'False', 'value': False}]`
- The later is required if you want to provide different display labels to your option values or in case you want to
- provide boolean values as options. In this case, you need to provide a string label for your boolean values as
- boolean values cannot be displayed properly as labels in the underlying Dash components.
+ The later is required if you want to provide different display labels to your option values or in case you want to provide boolean values as options. In this case, you need to provide a string label for your boolean values as boolean values cannot be displayed properly as labels in the underlying Dash components.
## Numerical selectors
@@ -36,11 +30,7 @@ For more information, refer to the API reference of the selector, or the documen
- [`RangeSlider`][vizro.models.RangeSlider] based on [`dcc.RangeSlider`](https://dash.plotly.com/dash-core-components/rangeslider)
!!! note
-
- When configuring the [`Slider`][vizro.models.Slider] and the [`RangeSlider`][vizro.models.RangeSlider] with float values, and using `step` with an integer value, you may notice
- unexpected behavior, such as the drag value being outside its indicated marks.
- To our knowledge, this is a current bug in the underlying [`dcc.Slider`](https://dash.plotly.com/dash-core-components/slider) and
- [`dcc.RangeSlider`](https://dash.plotly.com/dash-core-components/rangeslider) component, which you can circumvent by adapting the `step` size accordingly.
+ When configuring the [`Slider`][vizro.models.Slider] and the [`RangeSlider`][vizro.models.RangeSlider] with float values, and using `step` with an integer value, you may notice unexpected behavior, such as the drag value being outside its indicated marks. To our knowledge, this is a current bug in the underlying [`dcc.Slider`](https://dash.plotly.com/dash-core-components/slider) and [`dcc.RangeSlider`](https://dash.plotly.com/dash-core-components/rangeslider) component, which you can circumvent by adapting the `step` size as needed.
## Temporal selectors
@@ -49,7 +39,6 @@ For more information, refer to the API reference of the selector, or the documen
- [`DatePicker`][vizro.models.DatePicker] based on [`dmc.DateRangePicker`](https://www.dash-mantine-components.com/components/datepicker#daterangepicker) and [`dmc.DatePicker`](https://www.dash-mantine-components.com/components/datepicker)
!!! note
-
When the [`DatePicker`][vizro.models.DatePicker] is configured with `range=True` (the default), the underlying component is `dmc.DateRangePicker`. When `range=False` the underlying component is `dmc.DatePicker`.
When configuring the [`DatePicker`][vizro.models.DatePicker] make sure to provide your dates for `min`, `max` and `value` arguments in `"yyyy-mm-dd"` format or as `datetime` type (for example, `datetime.datetime(2024, 01, 01)`).
diff --git a/vizro-core/docs/pages/user-guides/table.md b/vizro-core/docs/pages/user-guides/table.md
index 19197c465..80e8e53dc 100755
--- a/vizro-core/docs/pages/user-guides/table.md
+++ b/vizro-core/docs/pages/user-guides/table.md
@@ -2,46 +2,32 @@
This guide shows you how to visualize tables in Vizro.
-There are two ways to visualize tables in Vizro, using either [AG Grid](#ag-grid) or [Dash DataTable](#dash-datatable).
-In general, [AG Grid](#ag-grid) is Vizro's recommended table implementation, but sometimes it may make sense to use the [Dash DataTable](#dash-datatable) instead.
+There are two ways to visualize tables in Vizro, using either [AG Grid](#ag-grid) or [Dash DataTable](#dash-datatable). In general, [AG Grid](#ag-grid) is Vizro's recommended table implementation, but sometimes it may make sense to use the [Dash DataTable](#dash-datatable) instead.
## Choose between AG Grid and Dash DataTable
-Vizro offers two models - the [`AgGrid`][vizro.models.AgGrid] model and the [`Table`][vizro.models.Table] model - for the above two approaches respectively.
-They both visualize tabular data in similar ways.
+Vizro offers two models - the [`AgGrid`][vizro.models.AgGrid] model and the [`Table`][vizro.models.Table] model - for the above two approaches respectively. They both visualize tabular data in similar ways.
-The main difference between the two is that the [`AgGrid`][vizro.models.AgGrid] model is based on Plotly's [Dash AG Grid](https://dash.plotly.com/dash-ag-grid) component,
-while the [`Table`][vizro.models.Table] model is based on the [Dash DataTable](https://dash.plotly.com/datatable) component.
-
-Both approaches have similar base features, and are configurable in similar ways. However, the AG Grid offers more advanced features out-of-the-box, is more customizable
-and also ships a powerful enterprise version. This is why it is Vizro's recommended table implementation. At the same time, the Dash DataTable can be used if developers are
-already familiar with it, or if some custom functionality is easier to implement using the Dash DataTable.
+The main difference between the two is that the [`AgGrid`][vizro.models.AgGrid] model is based on Plotly's [Dash AG Grid](https://dash.plotly.com/dash-ag-grid) component, while the [`Table`][vizro.models.Table] model is based on the [Dash DataTable](https://dash.plotly.com/datatable) component.
+Both approaches have similar base features, and are configurable in similar ways. However, the AG Grid offers more advanced features out-of-the-box, is more customizable and also ships a powerful enterprise version. This is why it is Vizro's recommended table implementation. At the same time, the Dash DataTable can be used if developers are already familiar with it, or if some custom functionality is easier to implement using the Dash DataTable.
## AG Grid
-[AG Grid](https://www.ag-grid.com/) is an interactive table/grid component designed for viewing, editing, and exploring large datasets. It
-is Vizro's recommended table implementation.
+[AG Grid](https://www.ag-grid.com/) is an interactive table/grid component designed for viewing, editing, and exploring large datasets. It is Vizro's recommended table implementation.
-The Vizro [`AgGrid`][vizro.models.AgGrid] model is based on the [Dash AG Grid](https://dash.plotly.com/dash-ag-grid), which is in turn based the
-original [Javascript implementation](https://www.ag-grid.com/).
+The Vizro [`AgGrid`][vizro.models.AgGrid] model is based on the [Dash AG Grid](https://dash.plotly.com/dash-ag-grid), which is in turn based the original [Javascript implementation](https://www.ag-grid.com/).
### Basic usage
To add a [`AgGrid`][vizro.models.AgGrid] to your page, do the following:
-1. Insert the [`AgGrid`][vizro.models.AgGrid] model into the `components` argument of the
-[`Page`][vizro.models.Page] model.
-2. Enter the `dash_ag_grid` function under the `figure` argument (imported via `from vizro.tables import dash_ag_grid`).
-
-The Vizro version of this AG Grid differs in one way from the original Dash AG Grid: it requires the user to pass a pandas DataFrame as the source of data.
-As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`. Most other [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments.
-Note that some defaults are set for some arguments (for example, for `columnDefs`) to help with styling and usability.
-Sometimes a parameter may not work because it requires a callback to function. In that case you can try [creating a custom AG Grid callable](custom-tables.md).
+1. Insert the [`AgGrid`][vizro.models.AgGrid] model into the `components` argument of the [`Page`][vizro.models.Page] model.
+1. Enter the `dash_ag_grid` function under the `figure` argument (imported via `from vizro.tables import dash_ag_grid`).
+The Vizro version of this AG Grid differs in one way from the original Dash AG Grid: it requires the user to pass a pandas DataFrame as the source of data. As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`. Most other [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments. Note that some defaults are set for some arguments (for example, for `columnDefs`) to help with styling and usability. Sometimes a parameter may not work because it requires a callback to function. In that case you can try [creating a custom AG Grid callable](custom-tables.md).
!!! example "Basic Dash AG Grid"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -59,29 +45,28 @@ Sometimes a parameter may not work because it requires a callback to function. I
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - figure:
- _target_: dash_ag_grid
- data_frame: gapminder
- type: ag_grid
- title: Default Dash AG Grid
+ - components:
+ - figure:
+ _target_: dash_ag_grid
+ data_frame: gapminder
+ type: ag_grid
+ title: Default Dash AG Grid
```
- === "Result"
- [![AGGrid]][AGGrid]
- [AGGrid]: ../../assets/user_guides/table/aggrid.png
+ === "Result"
+ [![AGGrid]][aggrid]
### Enable pagination
-Pagination is a visual alternative to using vertical scroll. It can also improve loading time if you have many rows.
-You can turn it on by setting `dashGridOptions={"pagination": True}`.
-!!! example "Basic Dash AG Grid"
+Pagination is a visual alternative to using vertical scroll. It can also improve loading time if you have many rows. You can turn it on by setting `dashGridOptions={"pagination": True}`.
+!!! example "Basic Dash AG Grid"
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -99,37 +84,34 @@ You can turn it on by setting `dashGridOptions={"pagination": True}`.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - figure:
- _target_: dash_ag_grid
- data_frame: gapminder
- dashGridOptions:
- pagination: true
- type: ag_grid
- title: Dash AG Grid with pagination
+ - components:
+ - figure:
+ _target_: dash_ag_grid
+ data_frame: gapminder
+ dashGridOptions:
+ pagination: true
+ type: ag_grid
+ title: Dash AG Grid with pagination
```
- === "Result"
- [![AGGrid]][AGGrid]
- [AGGrid]: ../../assets/user_guides/table/aggrid-pagination.png
+ === "Result"
+ [![AGGrid]][aggrid]
### Formatting columns
#### Numbers
-One of the most common tasks when working with tables is to format the columns so that displayed numbers are more readable.
-To do this, you can use the native functionality of [value formatters](https://dash.plotly.com/dash-ag-grid/value-formatters)
-or the Vizro pre-defined [custom cell data types](https://dash.plotly.com/dash-ag-grid/cell-data-types#providing-custom-cell-data-types) as shown below.
+One of the most common tasks when working with tables is to format the columns so that displayed numbers are more readable. To do this, you can use the native functionality of [value formatters](https://dash.plotly.com/dash-ag-grid/value-formatters) or the Vizro pre-defined [custom cell data types](https://dash.plotly.com/dash-ag-grid/cell-data-types#providing-custom-cell-data-types) as shown below.
The available custom cell types for Vizro are `dollar`, `euro`, `percent` and `numeric`.
-To use these, define your desired `` alongside the chosen `cellDataType` in
-the `columnDefs` argument of your `dash_ag_grid` function:
+To use these, define your desired `` alongside the chosen `cellDataType` in the `columnDefs` argument of your `dash_ag_grid` function:
```py
columnDefs = [{"field": "", "cellDataType": "euro"}]
@@ -138,7 +120,6 @@ columnDefs = [{"field": "", "cellDataType": "euro"}]
In the example below we select and format some columns of the gapminder data.
!!! example "AG Grid with formatted columns"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -168,6 +149,7 @@ In the example below we select and format some columns of the gapminder data.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -190,33 +172,23 @@ In the example below we select and format some columns of the gapminder data.
type: ag_grid
title: Example of AG Grid with formatted columns
```
- === "Result"
- [![AGGrid2]][AGGrid2]
- [AGGrid2]: ../../assets/user_guides/table/formatted_aggrid.png
+ === "Result"
+ [![AGGrid2]][aggrid2]
#### Dates
-For the [`AgGrid`][vizro.models.AgGrid] model to sort and filter dates correctly, the date must either be of
-string format `yyyy-mm-dd` (see [Dash AG Grid docs](https://dash.plotly.com/dash-ag-grid/date-filters#example:-date-filter))
-or a pandas datetime object. Any pandas datetime column will be transformed into the `yyyy-mm-dd` format automatically.
+For the [`AgGrid`][vizro.models.AgGrid] model to sort and filter dates correctly, the date must either be of string format `yyyy-mm-dd` (see [Dash AG Grid docs](https://dash.plotly.com/dash-ag-grid/date-filters#example:-date-filter)) or a pandas datetime object. Any pandas datetime column will be transformed into the `yyyy-mm-dd` format automatically.
#### Objects and strings
-No specific formatting is available for custom objects and strings, however you can make use of [Value Formatters](https://dash.plotly.com/dash-ag-grid/value-formatters)
-to format displayed strings automatically.
-
+No specific formatting is available for custom objects and strings, however you can make use of [Value Formatters](https://dash.plotly.com/dash-ag-grid/value-formatters) to format displayed strings automatically.
### Styling and changing the AG Grid
-As mentioned above, all [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments. Below you can find
-an example of a styled AG Grid where some conditional formatting is applied, and where the columns are editable, but
-not filterable or resizable. There are more ways to alter the grid beyond this showcase. AG Grid, like any other Vizro
-component, can be customized using custom CSS. You can find information in
-the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-selected-components).
+As mentioned above, all [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments. Below you can find an example of a styled AG Grid where some conditional formatting is applied, and where the columns are editable, but not filterable or resizable. There are more ways to alter the grid beyond this showcase. AG Grid, like any other Vizro component, can be customized using custom CSS. You can find information in the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-selected-components).
!!! example "Styled and modified Dash AG Grid"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -284,6 +256,7 @@ the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-select
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -299,28 +272,28 @@ the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-select
- field: year
- field: lifeExp
valueFormatter:
- function: "d3.format('.1f')(params.value)"
+ function: d3.format('.1f')(params.value)
- field: gdpPercap
valueFormatter:
- function: "d3.format('$,.1f')(params.value)"
+ function: d3.format('$,.1f')(params.value)
cellStyle:
styleConditions:
- condition: params.value < 1045
style:
- backgroundColor: "#ff9222"
+ backgroundColor: '#ff9222'
- condition: params.value >= 1045 && params.value <= 4095
style:
- backgroundColor: "#de9e75"
+ backgroundColor: '#de9e75'
- condition: params.value > 4095 && params.value <= 12695
style:
- backgroundColor: "#aaa9ba"
+ backgroundColor: '#aaa9ba'
- condition: params.value > 12695
style:
- backgroundColor: "#00b4ff"
+ backgroundColor: '#00b4ff'
- field: pop
type: rightAligned
valueFormatter:
- function: "d3.format(',.0f')(params.value)"
+ function: d3.format(',.0f')(params.value)
defaultColDef:
resizable: false
filter: false
@@ -329,10 +302,9 @@ the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-select
type: ag_grid
title: Example of a Dash AG Grid
```
- === "Result"
- [![AGGrid3]][AGGrid3]
- [AGGrid3]: ../../assets/user_guides/table/styled_aggrid.png
+ === "Result"
+ [![AGGrid3]][aggrid3]
If the available arguments are not sufficient, there is always the option to [create a custom AG Grid callable](custom-tables.md).
@@ -348,19 +320,14 @@ The Vizro [`Table`][vizro.models.Table] model is based on the [Dash DataTable](h
To add a [`Table`][vizro.models.Table] to your page, do the following:
-1. Insert the [`Table`][vizro.models.Table] model into the `components` argument of the
-[`Page`][vizro.models.Page] model.
-2. Enter the `dash_data_table` function under the `figure` argument (imported via `from vizro.tables import dash_data_table`).
-
+1. Insert the [`Table`][vizro.models.Table] model into the `components` argument of the [`Page`][vizro.models.Page] model.
+1. Enter the `dash_data_table` function under the `figure` argument (imported via `from vizro.tables import dash_data_table`).
-The Vizro version of this table differs in one way from the original table: it requires the user to pass a pandas DataFrame as the source of data.
-As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`.
+The Vizro version of this table differs in one way from the original table: it requires the user to pass a pandas DataFrame as the source of data. As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`.
-All other [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Note that we are
-setting some defaults for some arguments to help with styling.
+All other [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Note that we are setting some defaults for some arguments to help with styling.
!!! example "Dash DataTable"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -380,31 +347,29 @@ setting some defaults for some arguments to help with styling.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: dash_data_table
- data_frame: gapminder_2007
- title: Dash DataTable
- type: table
- title: Example of a Dash DataTable
+ - components:
+ - figure:
+ _target_: dash_data_table
+ data_frame: gapminder_2007
+ title: Dash DataTable
+ type: table
+ title: Example of a Dash DataTable
```
- === "Result"
- [![Table]][Table]
- [Table]: ../../assets/user_guides/table/table.png
+ === "Result"
+ [![Table]][table]
### Styling and changing the Dash DataTable
-As mentioned above, all [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Below you can find
-an example of a styled table where some conditional formatting is applied. There are many more ways to alter the table beyond this showcase.
+As mentioned above, all [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Below you can find an example of a styled table where some conditional formatting is applied. There are many more ways to alter the table beyond this showcase.
!!! example "Styled Dash DataTable"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -467,6 +432,7 @@ an example of a styled table where some conditional formatting is applied. There
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -504,12 +470,12 @@ an example of a styled table where some conditional formatting is applied. There
backgroundColor: dodgerblue
color: white
- if:
- filter_query: "{lifeExp} < 55"
+ filter_query: '{lifeExp} < 55'
column_id: lifeExp
- backgroundColor: "#85144b"
+ backgroundColor: '#85144b'
color: white
- if:
- filter_query: "{gdpPercap} > 10000"
+ filter_query: '{gdpPercap} > 10000'
column_id: gdpPercap
backgroundColor: green
color: white
@@ -524,26 +490,20 @@ an example of a styled table where some conditional formatting is applied. There
title: Dash DataTable
```
- === "Result"
- [![Table2]][Table2]
- [Table2]: ../../assets/user_guides/table/styled_table.png
+ === "Result"
+ [![Table2]][table2]
If the available arguments are not sufficient, there is always the option to create a [custom Dash DataTable](custom-tables.md).
-
## Add title, header, and footer
-The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] models accept a `title`, `header` and
-`footer` argument. This is useful for providing context to the data being displayed, or for adding a description of
-the data.
+The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] models accept a `title`, `header` and `footer` argument. This is useful for providing context to the data being displayed, or for adding a description of the data.
- **title**: Displayed as an [H3 header](https://dash.plotly.com/dash-html-components/h3), useful for summarizing the main topic or insight of the component.
- **header**: Accepts markdown text, ideal for extra descriptions, subtitles, or detailed data insights.
- **footer**: Accepts markdown text, commonly used for citing data sources, providing information on the last update, or adding disclaimers.
-
-
### Formatted AgGrid
!!! example "Formatted AgGrid"
@@ -571,30 +531,29 @@ the data.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: dash_ag_grid
- data_frame: gapminder_2007
- dashGridOptions:
- pagination: true
- title: Gapminder Data Insights
- header: |
- #### An Interactive Exploration of Global Health, Wealth, and Population
- footer: |
- SOURCE: **Plotly gapminder data set, 2024**
- type: ag_grid
- title: Formatted AgGrid
+ - components:
+ - figure:
+ _target_: dash_ag_grid
+ data_frame: gapminder_2007
+ dashGridOptions:
+ pagination: true
+ title: Gapminder Data Insights
+ header: |
+ #### An Interactive Exploration of Global Health, Wealth, and Population
+ footer: |
+ SOURCE: **Plotly gapminder data set, 2024**
+ type: ag_grid
+ title: Formatted AgGrid
```
- === "Result"
- [![FormattedGrid]][FormattedGrid]
-
- [FormattedGrid]: ../../assets/user_guides/components/formatted_aggrid.png
+ === "Result"
+ [![FormattedGrid]][formattedgrid]
### Formatted DataTable
@@ -623,24 +582,32 @@ the data.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: dash_data_table
- data_frame: gapminder_2007
- title: Gapminder Data Insights
- header: |
- #### An Interactive Exploration of Global Health, Wealth, and Population
- footer: |
- SOURCE: **Plotly gapminder data set, 2024**
- type: table
- title: Formatted DataTable
+ - components:
+ - figure:
+ _target_: dash_data_table
+ data_frame: gapminder_2007
+ title: Gapminder Data Insights
+ header: |
+ #### An Interactive Exploration of Global Health, Wealth, and Population
+ footer: |
+ SOURCE: **Plotly gapminder data set, 2024**
+ type: table
+ title: Formatted DataTable
```
- === "Result"
- [![FormattedTable]][FormattedTable]
- [FormattedTable]: ../../assets/user_guides/components/formatted_table.png
+ === "Result"
+ [![FormattedTable]][formattedtable]
+
+[aggrid]: ../../assets/user_guides/table/aggrid.png
+[aggrid2]: ../../assets/user_guides/table/formatted_aggrid.png
+[aggrid3]: ../../assets/user_guides/table/styled_aggrid.png
+[formattedgrid]: ../../assets/user_guides/components/formatted_aggrid.png
+[formattedtable]: ../../assets/user_guides/components/formatted_table.png
+[table]: ../../assets/user_guides/table/table.png
+[table2]: ../../assets/user_guides/table/styled_table.png
diff --git a/vizro-core/docs/pages/user-guides/tabs.md b/vizro-core/docs/pages/user-guides/tabs.md
index 09154177e..1811d0cac 100755
--- a/vizro-core/docs/pages/user-guides/tabs.md
+++ b/vizro-core/docs/pages/user-guides/tabs.md
@@ -1,8 +1,6 @@
# How to use tabs
-[`Tabs`][vizro.models.Tabs] organize and separate groups of related content in a dashboard, letting users switch between different sections or views.
-They are essentially a way of putting multiple [`Containers`][vizro.models.Container] in the same screen space, and letting the user switch between them.
-`Containers` enable the grouping of page components into sections and subsections. See our [user guide on `Containers`](container.md) for more information.
+[`Tabs`][vizro.models.Tabs] organize and separate groups of related content in a dashboard, letting users switch between different sections or views. They are essentially a way of putting multiple [`Containers`][vizro.models.Container] in the same screen space, and letting the user switch between them. `Containers` enable the grouping of page components into sections and subsections. See our [user guide on `Containers`](container.md) for more information.
{ width="400"}
@@ -16,14 +14,12 @@ This guide shows you how to use tabs to organize your `Containers` into subsecti
By using [`Tabs`][vizro.models.Tabs], the following applies:
- [`Filters`][vizro.models.Filter] affect all components on all tabs (opened and closed) of the page if not specified otherwise inside `Filter.targets`
-- The `title` of the [`Container`][vizro.models.Container] inserted into `Tabs.tabs` will be displayed as a tab label, and the title will be removed from the `Container`
-
+- The `title` of the [`Container`][vizro.models.Container] inserted into `Tabs.tabs` will be displayed as a tab label, and the title will be removed from the `Container`
To add [`Tabs`][vizro.models.Tabs] to your page, do the following:
1. Insert the [`Tabs`][vizro.models.Tabs] into the `components` argument of the [`Page`][vizro.models.Page]
-2. Insert your [`Containers`][vizro.models.Container] into the `tabs` argument of the [`Tabs`][vizro.models.Tabs]
-
+1. Insert your [`Containers`][vizro.models.Container] into the `tabs` argument of the [`Tabs`][vizro.models.Tabs]
!!! example "Tabs"
=== "app.py"
@@ -88,52 +84,53 @@ To add [`Tabs`][vizro.models.Tabs] to your page, do the following:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - tabs:
- - title: Tab I
- type: container
- components:
- - type: graph
- figure:
- _target_: bar
- data_frame: gapminder_2007
- title: Graph 1
- x: continent
- y: lifeExp
- color: continent
- - type: graph
- figure:
- _target_: box
- data_frame: gapminder_2007
- title: Graph 2
- x: continent
- y: lifeExp
- color: continent
- - title: Tab II
- type: container
- components:
- - type: graph
- figure:
- _target_: scatter
- data_frame: gapminder_2007
- title: Graph 3
- x: gdpPercap
- y: lifeExp
- size: pop
- color: continent
- type: tabs
+ components:
+ - type: tabs
+ tabs:
+ - title: Tab I
+ type: container
+ components:
+ - type: graph
+ figure:
+ _target_: bar
+ data_frame: gapminder_2007
+ title: Graph 1
+ x: continent
+ y: lifeExp
+ color: continent
+ - type: graph
+ figure:
+ _target_: box
+ data_frame: gapminder_2007
+ title: Graph 2
+ x: continent
+ y: lifeExp
+ color: continent
+ - title: Tab II
+ type: container
+ components:
+ - type: graph
+ figure:
+ _target_: scatter
+ data_frame: gapminder_2007
+ title: Graph 3
+ x: gdpPercap
+ y: lifeExp
+ size: pop
+ color: continent
controls:
- - type: filter
- column: continent
+ - type: filter
+ column: continent
title: Tabs
```
- === "Result"
- [![Tabs]][Tabs]
+ === "Result"
+ [![Tabs]][tabs]
- [Tabs]: ../../assets/user_guides/components/tabs.png
+[tabs]: ../../assets/user_guides/components/tabs.png
diff --git a/vizro-core/docs/pages/user-guides/themes.md b/vizro-core/docs/pages/user-guides/themes.md
index 6f78441d5..ac1d6fc7b 100644
--- a/vizro-core/docs/pages/user-guides/themes.md
+++ b/vizro-core/docs/pages/user-guides/themes.md
@@ -1,15 +1,13 @@
# How to use themes
-This guide shows you how to use themes. Themes are pre-designed collections of stylings that are applied to entire charts and dashboards.
-The themes provided by Vizro are infused with our design best practices that make charts and dashboards look visually consistent and professional.
+This guide shows you how to use themes. Themes are pre-designed collections of stylings that are applied to entire charts and dashboards. The themes provided by Vizro are infused with our design best practices that make charts and dashboards look visually consistent and professional.
## Themes in dashboards
-The [`Dashboard`][vizro.models.Dashboard] model accepts an optional `theme` argument, where you can choose between
-a `vizro_dark` and a `vizro_light` theme. If not specified then `theme` defaults to `vizro_dark`. The theme is applied to the entire dashboard and its charts/components when a user first loads your dashboard. Regardless of the theme applied on first load, users can always switch between light and dark themes via the toggle button in the upper-right corner of the dashboard.
+
+The [`Dashboard`][vizro.models.Dashboard] model accepts an optional `theme` argument, where you can choose between a `vizro_dark` and a `vizro_light` theme. If not specified then `theme` defaults to `vizro_dark`. The theme is applied to the entire dashboard and its charts/components when a user first loads your dashboard. Regardless of the theme applied on first load, users can always switch between light and dark themes via the toggle button in the upper-right corner of the dashboard.
!!! example "Change theme"
=== "app.py"
-
```{.python pycafe-link hl_lines="18"}
import vizro.models as vm
import vizro.plotly.express as px
@@ -32,47 +30,40 @@ a `vizro_dark` and a `vizro_light` theme. If not specified then `theme` defaults
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml hl_lines="12"
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: scatter_matrix
- color: species
- data_frame: iris
- dimensions: ["sepal_length", "sepal_width", "petal_length", "petal_width"]
- type: graph
- title: Changing themes
+ - components:
+ - figure:
+ _target_: scatter_matrix
+ color: species
+ data_frame: iris
+ dimensions: [sepal_length, sepal_width, petal_length, petal_width]
+ type: graph
+ title: Changing themes
theme: vizro_light
```
+
=== "Result - vizro_light"
- [![Light]][Light]
+ [![Light]][light]
- [Light]: ../../assets/user_guides/themes/light.png
=== "Result - vizro_dark"
- [![Dark]][Dark]
-
- [Dark]: ../../assets/user_guides/themes/dark.png
-
+ [![Dark]][dark]
## Themes in plotly charts
You can also use our templates for plotly charts outside the dashboard. This is useful in a few contexts:
-* Creation of standalone charts to be used independently of a Vizro dashboard.
-* Rapid development of charts for eventual use in a Vizro dashboard, for example in a Jupyter Notebook.
+- Creation of standalone charts to be used independently of a Vizro dashboard.
+- Rapid development of charts for eventual use in a Vizro dashboard, for example in a Jupyter Notebook.
!!! note
+ Using `import vizro.plotly.express as px` is equal to using `import plotly.express as px`, but with the added benefit of being able to integrate the resulting chart code into a Vizro dashboard. Vizro offers a minimal layer on top of Plotly's existing charting library, allowing you to seamlessly use all the existing charts and functionalities provided by plotly.express without any modifications.
- Using `import vizro.plotly.express as px` is equivalent to using `import plotly.express as px`,
- but with the added benefit of being able to integrate the resulting chart code into a Vizro dashboard.
- Vizro offers a minimal layer on top of Plotly's existing charting library, allowing you to seamlessly use all the
- existing charts and functionalities provided by plotly.express without any modifications.
-
-Our `vizro_dark` and `vizro_light` themes are automatically registered to `plotly.io.templates` when importing Vizro.
-Consult the plotly documentation for [more details on how templates work in plotly](https://plotly.com/python/templates/#theming-and-templates).
+Our `vizro_dark` and `vizro_light` themes are automatically registered to `plotly.io.templates` when importing Vizro. Consult the plotly documentation for [more details on how templates work in plotly](https://plotly.com/python/templates/#theming-and-templates).
By default, plots imported from `vizro.plotly.express` have the `vizro_dark` theme applied. This can be altered either globally or for individual plots.
@@ -87,14 +78,20 @@ pio.templates.default = "vizro_light"
```
### Set themes for selected charts
+
To change the template for a selected chart only, use the `template` parameter and run:
```python
import vizro.plotly.express as px
df = px.data.iris()
-px.scatter_matrix(df,
- dimensions=["sepal_length", "sepal_width", "petal_length", "petal_width"],
- color="species",
- template="vizro_light")
+px.scatter_matrix(
+ df,
+ dimensions=["sepal_length", "sepal_width", "petal_length", "petal_width"],
+ color="species",
+ template="vizro_light",
+)
```
+
+[dark]: ../../assets/user_guides/themes/dark.png
+[light]: ../../assets/user_guides/themes/light.png
diff --git a/vizro-core/docs/pages/user-guides/visual-formatting.md b/vizro-core/docs/pages/user-guides/visual-formatting.md
index 7b384f3e9..56d1d2d52 100644
--- a/vizro-core/docs/pages/user-guides/visual-formatting.md
+++ b/vizro-core/docs/pages/user-guides/visual-formatting.md
@@ -1,17 +1,13 @@
# How to customize the style of Vizro dashboards
-Vizro has a default styling to help users with no design experience get started.
-There are several options if you want to customize the style:
+Vizro has a default styling to help users with no design experience get started. There are several options if you want to customize the style:
-* **[Configure the `Layout`](layouts.md)**: Customize the arrangement of your components inside your Vizro dashboard.
+- **[Configure the `Layout`](layouts.md)**: Customize the arrangement of your components inside your Vizro dashboard.
-* **[Apply a theme](themes.md)**: Choose between a dark or light theme.
+- **[Apply a theme](themes.md)**: Choose between a dark or light theme.
-* **[Manage assets](assets.md)**: Enhance your dashboard by adding images, scripts, and stylesheets to your assets folder.
+- **[Manage assets](assets.md)**: Enhance your dashboard by adding images, scripts, and stylesheets to your assets folder.
-* **[Customize CSS](custom-css.md)**: Incorporate custom CSS to deviate from the default styling and create a
-unique appearance for your Vizro dashboard.
+- **[Customize CSS](custom-css.md)**: Incorporate custom CSS to deviate from the default styling and create a unique appearance for your Vizro dashboard.
-* **[Customize your `component`](components.md)**: Change the appearance of components like the [Graph](graph.md), the
-[Table](table.md) and the [AgGrid](table.md), by passing extra arguments. Refer to the relevant user guide for
-more details.
+- **[Customize your `component`](components.md)**: Change the appearance of components like the [Graph](graph.md), the [Table](table.md) and the [AgGrid](table.md), by passing extra arguments. Refer to the relevant user guide for more details.
diff --git a/vizro-core/examples/README.md b/vizro-core/examples/README.md
index 72146bfb7..53cf932b7 100644
--- a/vizro-core/examples/README.md
+++ b/vizro-core/examples/README.md
@@ -4,8 +4,7 @@ Please note that this folder contains only example dashboards that are still **i
### Vizro examples gallery
-To view a comprehensive list of available demos, please visit our [examples gallery](http://vizro.mckinsey.com/).
-There, you can explore a wide range of dashboards and applications created with Vizro.
+To view a comprehensive list of available demos, please visit our [examples gallery](http://vizro.mckinsey.com/). There, you can explore a wide range of dashboards and applications created with Vizro.
diff --git a/vizro-core/examples/visual-vocabulary/README.md b/vizro-core/examples/visual-vocabulary/README.md
index 3b298520e..e59b3103c 100644
--- a/vizro-core/examples/visual-vocabulary/README.md
+++ b/vizro-core/examples/visual-vocabulary/README.md
@@ -2,14 +2,11 @@
### Welcome to our visual vocabulary dashboard! 🎨
-This dashboard serves as a comprehensive guide for selecting and creating various types of charts. It helps you decide
-when to use each chart type, and offers sample Python code using [Plotly](https://plotly.com/python/), and
-instructions for embedding these charts into a [Vizro](https://github.com/mckinsey/vizro) dashboard.
+This dashboard serves as a comprehensive guide for selecting and creating various types of charts. It helps you decide when to use each chart type, and offers sample Python code using [Plotly](https://plotly.com/python/), and instructions for embedding these charts into a [Vizro](https://github.com/mckinsey/vizro) dashboard.
The charts in this dashboard are designed to make it easy for anyone to create beautiful and sophisticated visuals.
-Our goal is to help you understand best practices in data visualization, ensure your charts effectively communicate
-your message, and streamline the creation of high-quality, interactive visualizations.
+Our goal is to help you understand best practices in data visualization, ensure your charts effectively communicate your message, and streamline the creation of high-quality, interactive visualizations.
Created by:
@@ -19,12 +16,9 @@ Created by:
Inspired by:
-- [The FT Visual Vocabulary](https://github.com/Financial-Times/chart-doctor/blob/main/visual-vocabulary/README.md):
- [Alan Smith](https://github.com/alansmithy), [Chris Campbell](https://github.com/digitalcampbell), Ian Bott,
- Liz Faunce, Graham Parrish, Billy Ehrenberg, Paul McCallum, [Martin Stabe](https://github.com/martinstabe).
+- [The FT Visual Vocabulary](https://github.com/Financial-Times/chart-doctor/blob/main/visual-vocabulary/README.md): [Alan Smith](https://github.com/alansmithy), [Chris Campbell](https://github.com/digitalcampbell), Ian Bott, Liz Faunce, Graham Parrish, Billy Ehrenberg, Paul McCallum, [Martin Stabe](https://github.com/martinstabe).
-- [The Graphic Continuum](https://www.informationisbeautifulawards.com/showcase/611-the-graphic-continuum):
- Jon Swabish and Severino Ribecca
+- [The Graphic Continuum](https://www.informationisbeautifulawards.com/showcase/611-the-graphic-continuum): Jon Swabish and Severino Ribecca
Credits and sources:
@@ -102,13 +96,12 @@ The dashboard is still in development. Below is an overview of the chart types f
Contributions are welcome! To contribute a chart, follow the steps below:
1. Check that a `svg` file named after the chart type is contained in the [assets](https://github.com/mckinsey/vizro/tree/main/vizro-core/examples/visual-vocabulary/assets/images/charts) folder. If not, [raise an issue](https://github.com/mckinsey/vizro/issues) in the repository.
-2. Add a `.py` file containing a code example of the chart type in the `pages/examples` folder, for instance, `area.py`. Take a look at existing examples.
-3. Create a new page for the chart type and add it to the relevant category `.py` file such as `correlation.py`,
- `deviation.py`, `distribution.py`, etc. Ensure you add the page to the list of `pages` at the end of the `.py` file.
-4. Remove the `IncompletePage(..)` entry for that chart type in `chart_groups.py`.
-5. Update this `README.md` with the new chart type, its status, category, and API links.
+1. Add a `.py` file containing a code example of the chart type in the `pages/examples` folder, for instance, `area.py`. Take a look at existing examples.
+1. Create a new page for the chart type and add it to the relevant category `.py` file such as `correlation.py`, `deviation.py`, `distribution.py`, etc. Ensure you add the page to the list of `pages` at the end of the `.py` file.
+1. Remove the `IncompletePage(..)` entry for that chart type in `chart_groups.py`.
+1. Update this `README.md` with the new chart type, its status, category, and API links.
## How to run the example locally
1. Run the example with the command `hatch run example visual-vocabulary`.
-2. You should now be able to access the app locally via http://127.0.0.1:8051/.
+1. You should now be able to access the app locally via http://127.0.0.1:8051/.
+
+ ## Header level 2
+
+ ### Header level 3
+
+ #### Header level 4
+ type: card
+ - text: |
+ Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
+
+ Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
+
+ Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
+
+ Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
+ title: Paragraphs
+ type: card
+ - text: |
+ >
+ > A block quote is a long quotation, indented to create a separate block of text.
+ >
+ title: Block Quotes
+ type: card
+ - text: |
+ * Item A
+ * Sub Item 1
+ * Sub Item 2
+ * Item B
+ title: Lists
+ type: card
+ - text: |
+ This word will be *italic*
+
+ This word will be **bold**
+
+ This word will be _**bold and italic**_
+ title: Emphasis
+ type: card
+ title: Customizing Text
```
- === "Result"
- [![CardText]][CardText]
- [CardText]: ../../assets/user_guides/components/card_text.png
+ === "Result"
+ [![CardText]][cardtext]
### Place an image on a card
@@ -189,11 +185,10 @@ Images can be added to the `text` parameter by using the standard markdown synta
``
-An image ALT text offers a description to your image and serves as a text placeholder or to improve the
-accessibility of your app. Providing an image ALT text is optional.
+An image ALT text offers a description to your image and serves as a text placeholder or to improve the accessibility of your app. Providing an image ALT text is optional.
1. To use a relative Image URL, place an image of your choice into your `assets` folder first
-2. Use markdown to render your image by using one of the following syntax:
+1. Use markdown to render your image by using one of the following syntax:
- Relative Image URL: ``
- Absolute Image URL: ``
@@ -228,55 +223,50 @@ accessibility of your app. Providing an image ALT text is optional.
Run and edit this code in PyCafe
-
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - text: |
- 
+ - components:
+ - text: |
+ 
- Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
+ Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
- Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
+ Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
- Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
- title: My card with image!
- type: card
- title: Placing Images
+ Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
+ title: My card with image!
+ type: card
+ title: Placing Images
```
- === "Result"
- [![CardImageDefault]][CardImageDefault]
- [CardImageDefault]: ../../assets/user_guides/components/card_image_default.png
+ === "Result"
+ [![CardImageDefault]][cardimagedefault]
!!! note
-
- Note that inserting images using html is by default turned off by the `dcc.Markdown` to prevent users being exposed
- to cross-site scripting attacks. If you need to turn it on, a custom component would have to be created.
+ Note that inserting images using HTML is by default turned off by the `dcc.Markdown` to prevent users being exposed to cross-site scripting attacks. If you need to turn it on, a custom component would have to be created.
You might notice that the image is quite large. You'll find out how to style images in terms of their position and size in the next section.
-
### Style a card image
To change the size or position of the image, add a URL hash to your image like this:
``
-Note the added URL hash `#my-image`. Now create a CSS file placed in your `assets` folder
-and give an attribute selector to select images with that matching URL hash.
+Note the added URL hash `#my-image`. Now create a CSS file placed in your `assets` folder and give an attribute selector to select images with that matching URL hash.
!!! example "Card with styled image"
=== "images.css"
- ```css
- img[src*="#my-image"] {
- width: 120px;
- height: 120px;
- }
- ```
+ ```css
+ img[src*="#my-image"] {
+ width: 120px;
+ height: 120px;
+ }
+ ```
+
=== "app.py"
```py
import vizro.models as vm
@@ -313,23 +303,22 @@ and give an attribute selector to select images with that matching URL hash.
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - text: |
- 
+ - components:
+ - text: |
+ 
- Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
+ Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
- Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
+ Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
- Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
- title: My card with image!
- type: card
- title: Styling Images
+ Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
+ title: My card with image!
+ type: card
+ title: Styling Images
```
- === "Result"
- [![CardImageStyled]][CardImageStyled]
- [CardImageStyled]: ../../assets/user_guides/components/card_image_styled.png
+ === "Result"
+ [![CardImageStyled]][cardimagestyled]
Use the following pre-defined URL hashes in your image path to apply Vizro's default styling.
@@ -341,12 +330,13 @@ Use the following pre-defined URL hashes in your image path to apply Vizro's def
!!! example "Card with floating image"
=== "images.css"
- ```css
- img[src*="#my-image"] {
- width: 120px;
- height: 120px;
- }
- ```
+ ```css
+ img[src*="#my-image"] {
+ width: 120px;
+ height: 120px;
+ }
+ ```
+
=== "app.py"
```py
import vizro.models as vm
@@ -389,29 +379,28 @@ Use the following pre-defined URL hashes in your image path to apply Vizro's def
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - text: |
- 
+ - components:
+ - text: |
+ 
- Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
+ Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
- Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
+ Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
- Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
+ Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
- Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
+ Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
- Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
+ Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
- Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
- title: My card with floating image!
- type: card
- title: Floating Images
+ Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
+ title: My card with floating image!
+ type: card
+ title: Floating Images
```
- === "Result"
- [![CardImageFloating]][CardImageFloating]
- [CardImageFloating]: ../../assets/user_guides/components/card_image_floating.png
+ === "Result"
+ [![CardImageFloating]][cardimagefloating]
#### Card with icon
@@ -442,38 +431,34 @@ Use the following pre-defined URL hashes in your image path to apply Vizro's def
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - text: |
- 
+ - components:
+ - text: |
+ 
- ### Card Title
+ ### Card Title
- Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut fringilla dictum lacus eget fringilla.
- Maecenas in various nibh, quis venenatis nulla. Integer et libero ultrices, scelerisque velit sed.
- type: card
- title: Card with icon
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut fringilla dictum lacus eget fringilla.
+ Maecenas in various nibh, quis venenatis nulla. Integer et libero ultrices, scelerisque velit sed.
+ type: card
+ title: Card with icon
```
- === "Result"
- [![CardIcon]][CardIcon]
-
- [CardIcon]: ../../assets/user_guides/components/card_icon.png
+ === "Result"
+ [![CardIcon]][cardicon]
### Make an icon responsive to theme switch
-To make an icon responsive to the theme switch, override the value of the [`filter` CSS property](https://developer.mozilla.org/en-US/docs/Web/CSS/filter).
-The `filter` CSS property lets you add visual effects to elements using different functions. In our example, we're using the `--inverse-color` CSS variable from the Vizro theme.
-It uses the CSS `invert()` function to flip the color of the icon when you switch themes. Note that this only works if your initial icon has a white fill color. If your icon is not white, you can change its color by adding `fill="white"` to the SVG code.
-Assign the predefined CSS variable `--inverse-color` to the `filter` property of your selected icon.
+To make an icon responsive to the theme switch, override the value of the [`filter` CSS property](https://developer.mozilla.org/en-US/docs/Web/CSS/filter). The `filter` CSS property lets you add visual effects to elements using different functions. In our example, we're using the `--inverse-color` CSS variable from the Vizro theme. It uses the CSS `invert()` function to flip the color of the icon when you switch themes. Note that this only works if your initial icon has a white fill color. If your icon is not white, you can change its color by adding `fill="white"` to the SVG code. Assign the predefined CSS variable `--inverse-color` to the `filter` property of your selected icon.
```css
img[src*="#my-image"] {
- filter: var(--inverse-color);
+ filter: var(--inverse-color);
}
```
@@ -482,18 +467,15 @@ img[src*="#my-image"] {
### Create a navigation card
-This section describes how to use the [`Card`][vizro.models.Card] component to create a navigation card,
-enabling users to navigate to another page by clicking on the card area.
+This section describes how to use the [`Card`][vizro.models.Card] component to create a navigation card, enabling users to navigate to another page by clicking on the card area.
-For a button-style link navigation component, see the [separate guide on creating a link button](#create-a-link-button).
-To configure the navigation panel on the left hand side of the screen, refer to the
-[separate guide on navigation](navigation.md).
+For a button-style link navigation component, see the [separate guide on creating a link button](#create-a-link-button). To configure the navigation panel on the left hand side of the screen, refer to the [separate guide on navigation](navigation.md).
To create a navigation card:
1. Insert the [`Card`][vizro.models.Card] into the `components` argument of the [`Page`][vizro.models.Page].
-2. Pass your markdown text to the `Card.text`.
-3. Pass a relative or absolute URL to the `Card.href`.
+1. Pass your markdown text to the `Card.text`.
+1. Pass a relative or absolute URL to the `Card.href`.
!!! example "Navigation Card"
=== "app.py"
@@ -537,72 +519,65 @@ To create a navigation card:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - text: |
- ### Filters and parameters
-
- Leads to the first page on click
- href: /filters-and-parameters
- type: card
- - text: |
- ### Google - External Link
-
- Leads to an external link on click.
- href: https://google.com
- type: card
- title: Homepage
- - components:
- - figure:
- _target_: scatter
- color: sepal_width
- data_frame: iris
- x: sepal_length
- y: petal_width
- type: graph
- title: Filters and parameters
+ - components:
+ - text: |
+ ### Filters and parameters
+
+ Leads to the first page on click
+ href: /filters-and-parameters
+ type: card
+ - text: |
+ ### Google - External Link
+
+ Leads to an external link on click.
+ href: https://google.com
+ type: card
+ title: Homepage
+ - components:
+ - figure:
+ _target_: scatter
+ color: sepal_width
+ data_frame: iris
+ x: sepal_length
+ y: petal_width
+ type: graph
+ title: Filters and parameters
```
- === "Result"
- [![NavCard]][NavCard]
- [NavCard]: ../../assets/user_guides/components/nav_card.png
+ === "Result"
+ [![NavCard]][navcard]
If you now click on the card area, you should automatically be redirected to the relevant `href`.
!!! note
-
When using the [`Card`][vizro.models.Card], keep the following in mind:
- If the href given is a relative URL, it should match the `path` of the [`Page`][vizro.models.Page] that the [`Card`][vizro.models.Card] should navigate to.
- If the href given is an absolute link, it should start with `https://` or an equivalent protocol.
-
### Create a KPI card
-To create a KPI card, you can use the existing KPI card functions from [`vizro.figures`](../API-reference/figure-callables.md).
-Unlike the static text card `vm.Card`, a KPI card must be created using a figure function,
-which enables the text content of the KPI to change based on input from controls or actions.
+
+To create a KPI card, you can use the existing KPI card functions from [`vizro.figures`](../API-reference/figure-callables.md). Unlike the static text card `vm.Card`, a KPI card must be created using a figure function, which enables the text content of the KPI to change based on input from controls or actions.
For detailed examples on how to create a KPI card, refer to the [figure user guide on KPI cards](figure.md#key-performance-indicator-kpi-cards).
## Buttons
-The Button component is commonly used for interactive dashboard interactions
-such as form submissions, navigation links, and other action triggers.
-
-To add a [`Button`][vizro.models.Button], insert it into the `components` argument of the
-[`Page`][vizro.models.Page].
+The Button component is commonly used for interactive dashboard interactions such as form submissions, navigation links, and other action triggers.
+To add a [`Button`][vizro.models.Button], insert it into the `components` argument of the [`Page`][vizro.models.Page].
### Customize button text
You can configure the `text` argument to alter the display text of the [`Button`][vizro.models.Button].
!!! example "Customize text"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -616,26 +591,24 @@ You can configure the `text` argument to alter the display text of the [`Button`
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- components:
- - type: button
- text: I'm a button!
+ - type: button
+ text: I'm a button!
title: Button with text
```
- === "Result"
- [![ButtonText]][ButtonText]
-
- [ButtonText]: ../../assets/user_guides/components/button_text.png
+ === "Result"
+ [![ButtonText]][buttontext]
### Create a link button
-To navigate to a different page using a button with an anchor tag, assign an absolute or relative URL to the
-`Button.href`.
+To navigate to a different page using a button with an anchor tag, assign an absolute or relative URL to the `Button.href`.
```python
import vizro.models as vm
@@ -645,16 +618,11 @@ vm.Button(text="Leave us a star! ⭐", href="https://github.com/mckinsey/vizro")
### Attach an action
-You can use the [`Button`][vizro.models.Button] to trigger predefined action functions, such as exporting data.
-To explore the available options for [`Actions`][vizro.models.Action], refer to our [API reference][vizro.actions].
-Use the `Button.actions` argument to specify which action function executes when the button is clicked.
-
-The example below demonstrates how to configure a button to export the filtered data of a target chart using the
-[export_data][vizro.actions.export_data] action function.
+You can use the [`Button`][vizro.models.Button] to trigger predefined action functions, such as exporting data. To explore the available options for [`Actions`][vizro.models.Action], refer to our [API reference][vizro.actions]. Use the `Button.actions` argument to specify which action function executes when the button is clicked.
+The example below demonstrates how to configure a button to export the filtered data of a target chart using the [export_data][vizro.actions.export_data] action function.
!!! example "Button with action"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -690,29 +658,30 @@ The example below demonstrates how to configure a button to export the filtered
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- components:
- - figure:
- _target_: scatter
- x: sepal_width
- y: sepal_length
- color: species
- size: petal_length
- data_frame: iris
- id: scatter_chart
- type: graph
- - type: button
- text: Export data
- id: export_data
- actions:
- - function:
- _target_: export_data
- targets:
- - scatter_chart
+ - figure:
+ _target_: scatter
+ x: sepal_width
+ y: sepal_length
+ color: species
+ size: petal_length
+ data_frame: iris
+ id: scatter_chart
+ type: graph
+ - type: button
+ text: Export data
+ id: export_data
+ actions:
+ - function:
+ _target_: export_data
+ targets:
+ - scatter_chart
controls:
- column: species
selector:
@@ -728,14 +697,13 @@ The example below demonstrates how to configure a button to export the filtered
- [1]
title: My first page
```
- === "Result"
- [![Button]][Button]
- [Button]: ../../assets/user_guides/components/button.png
+ === "Result"
+ [![Button]][button]
### Use as a control
-The [`Button`][vizro.models.Button] component is currently reserved to be used inside the main panel (right-side) of the dashboard.
-However, there might be use cases where one would like to place the `Button` inside the control panel (left-side) with the other controls.
+
+The [`Button`][vizro.models.Button] component is currently reserved to be used inside the main panel (right-side) of the dashboard. However, there might be use cases where one would like to place the `Button` inside the control panel (left-side) with the other controls.
In this case, follow the user-guide outlined for [creating custom components](custom-components.md) and manually add the `Button` as a valid type to the `controls` argument by running the following lines before your dashboard configurations:
@@ -748,3 +716,13 @@ vm.Page.add_type("controls", vm.Button)
# Add dashboard configurations below
...
```
+
+[button]: ../../assets/user_guides/components/button.png
+[buttontext]: ../../assets/user_guides/components/button_text.png
+[card]: ../../assets/user_guides/components/card.png
+[cardicon]: ../../assets/user_guides/components/card_icon.png
+[cardimagedefault]: ../../assets/user_guides/components/card_image_default.png
+[cardimagefloating]: ../../assets/user_guides/components/card_image_floating.png
+[cardimagestyled]: ../../assets/user_guides/components/card_image_styled.png
+[cardtext]: ../../assets/user_guides/components/card_text.png
+[navcard]: ../../assets/user_guides/components/nav_card.png
diff --git a/vizro-core/docs/pages/user-guides/components.md b/vizro-core/docs/pages/user-guides/components.md
index 106bf6a0b..45ea5a123 100755
--- a/vizro-core/docs/pages/user-guides/components.md
+++ b/vizro-core/docs/pages/user-guides/components.md
@@ -1,8 +1,6 @@
# Components
-The [`Page`][vizro.models.Page] model accepts the `components` argument, where you can enter any of the components
-listed below to fill your dashboard with visuals.
-
+The [`Page`][vizro.models.Page] model accepts the `components` argument, where you can enter any of the components listed below to fill your dashboard with visuals.
@@ -38,7 +36,6 @@ listed below to fill your dashboard with visuals.
[:octicons-arrow-right-24: View user guide](card-button.md)
-
- :octicons-table-16:{ .lg .middle } __Containers__
---
diff --git a/vizro-core/docs/pages/user-guides/container.md b/vizro-core/docs/pages/user-guides/container.md
index c7e327c5f..2f379709e 100755
--- a/vizro-core/docs/pages/user-guides/container.md
+++ b/vizro-core/docs/pages/user-guides/container.md
@@ -2,30 +2,22 @@
This guide shows you how to use containers to group your components into sections and subsections within the page.
-A [`Container`][vizro.models.Container] complements the idea of a [`Page`][vizro.models.Page], and the two models have almost identical arguments.
- [`Page.layout`](layouts.md) offers a way to structure the overall layout of the page, and a `Container` enables more granular control within a specific section of that page.
+A [`Container`][vizro.models.Container] complements the idea of a [`Page`][vizro.models.Page], and the two models have almost identical arguments. [`Page.layout`](layouts.md) offers a way to structure the overall layout of the page, and a `Container` enables more granular control within a specific section of that page.
-While there is currently no clear difference in rendering, extra functionality will be added to the `Container` soon (including controls specific to that container),
-enhancing the ability to manage related components.
+While there is currently no clear difference in rendering, extra functionality will be added to the `Container` soon (including controls specific to that container), enhancing the ability to manage related components.
!!! note "Displaying multiple containers inside Tabs"
-
An alternative way to display multiple containers on one page is to place them inside [Tabs](tabs.md).
- [`Tabs`][vizro.models.Tabs] organize and separate groups of related content in a dashboard, letting users switch between different sections or views.
- They are a way of putting multiple containers into the same screen space, and letting the user switch between them.
+ [`Tabs`][vizro.models.Tabs] organize and separate groups of related content in a dashboard, letting users switch between different sections or views. They are a way of putting multiple containers into the same screen space, and letting the user switch between them.
{ width="500" }
-
-
## When to use containers
-In general, any arbitrarily granular layout can already be achieved by [using `Page.layout`](layouts.md) alone and is our
-recommended approach if you want to arrange components on a page with consistent row and/or column spacing.
-`Page.layout` has a `grid` argument that sets the overall layout of the page.
-`Container.layout` also has a `grid` argument. This enables you to insert a further `grid` into a component's space on the page,
-enabling more granular control by breaking the overall page grid into subgrids.
+In general, any arbitrarily granular layout can already be achieved by [using `Page.layout`](layouts.md) alone and is our recommended approach if you want to arrange components on a page with consistent row and/or column spacing.
+
+`Page.layout` has a `grid` argument that sets the overall layout of the page. `Container.layout` also has a `grid` argument. This enables you to insert a further `grid` into a component's space on the page, enabling more granular control by breaking the overall page grid into subgrids.
Here are a few cases where you might want to use a `Container` instead of `Page.layout`:
@@ -34,14 +26,14 @@ Here are a few cases where you might want to use a `Container` instead of `Page.
- If you want different row and column spacing between subgrids
- If you want to apply controls to selected subgrids (will be supported soon)
-
## Basic containers
+
To add a [`Container`][vizro.models.Container] to your page, do the following:
1. Insert the `Container` into the `components` argument of the [`Page`][vizro.models.Page]
-2. Set a `title` for your `Container`
-3. Configure your `components`, [read the overview page for various options](components.md)
-4. (optional) Configure your `layout`, see [the guide on `Layout`](layouts.md)
+1. Set a `title` for your `Container`
+1. Configure your `components`, [read the overview page for various options](components.md)
+1. (optional) Configure your `layout`, see [the guide on `Layout`](layouts.md)
!!! example "Container"
=== "app.py"
@@ -105,7 +97,7 @@ To add a [`Container`][vizro.models.Container] to your page, do the following:
```
1. Note that the `Page.layout` argument is not specified here and will therefore defaults to `[[0], [1]]`, meaning the containers will be **vertically stacked** down the page in one column.
- 2. **Horizontally stack** the components side-by-side inside this `Container` in one row.
+ 1. **Horizontally stack** the components side-by-side inside this `Container` in one row.
=== "app.yaml"
```yaml
@@ -149,27 +141,20 @@ To add a [`Container`][vizro.models.Container] to your page, do the following:
title: Container II
title: Containers
```
- === "Result"
- [![Container]][Container]
- [Container]: ../../assets/user_guides/components/containers.png
+ === "Result"
+ [![Container]][container]
Note that an almost identical layout can also be achieved using solely the [`Page.layout`](layouts.md) by configuring the `Page.layout` as `vm.Layout(grid = [[0, 1], [2, 2]])`.
## Nested containers
-Containers can be nested, providing a hierarchical structure for organizing components.
-This nesting capability enables users to create more complex layouts and manage related components at any level of granularity.
+
+Containers can be nested, providing a hierarchical structure for organizing components. This nesting capability enables users to create more complex layouts and manage related components at any level of granularity.
To create nested containers, add a `Container` to the `components` argument of another `Container`.
```python title="Example"
-vm.Container(
- title="Parent Container",
- components=[
- vm.Container(
- title="Child Container",
- components=[vm.Button()]
- )
- ]
-)
+vm.Container(title="Parent Container", components=[vm.Container(title="Child Container", components=[vm.Button()])])
```
+
+[container]: ../../assets/user_guides/components/containers.png
diff --git a/vizro-core/docs/pages/user-guides/custom-actions.md b/vizro-core/docs/pages/user-guides/custom-actions.md
index e5fa3afd8..2fb66cd2c 100644
--- a/vizro-core/docs/pages/user-guides/custom-actions.md
+++ b/vizro-core/docs/pages/user-guides/custom-actions.md
@@ -1,17 +1,16 @@
# How to create custom actions
-This guide demonstrates the usage of custom actions, an idea that shares similarities with, but is not identical to [callbacks](https://dash.plotly.com/basic-callbacks) in `Dash`.
-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.
+This guide demonstrates the usage of custom actions, an idea that shares similarities with, but is not identical to [callbacks](https://dash.plotly.com/basic-callbacks) in `Dash`. 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.
+
## Simple custom action
Custom actions enable you to implement your own action function. Simply do the following:
1. define a function
-2. decorate it with the `@capture("action")` decorator
-3. add it as a `function` argument inside the [`Action`][vizro.models.Action] model
+1. decorate it with the `@capture("action")` decorator
+1. add it as a `function` argument inside the [`Action`][vizro.models.Action] model
The following example shows how to create a custom action that postpones execution of the next action in the chain for `t` seconds.
@@ -58,27 +57,24 @@ The following example shows how to create a custom action that postpones executi
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
- ```yaml
- # Custom actions are currently only possible via Python configuration
- ```
-
+ Custom actions are currently only possible via Python configuration.
+
## Interact with inputs and outputs
+
When a custom action needs to interact with the dashboard, it is possible to define `inputs` and `outputs` for the custom action.
-- `inputs` represents dashboard component properties whose values are passed to the custom action function as arguments.
-It is a list of strings in the format `"."` (for example, `"my_selector.value`").
-- `outputs` represents dashboard component properties corresponding to the custom action function return value(s).
-Similar to `inputs`, it is a list of strings in the format `"."` (for example, `"my_card.children"`).
+- `inputs` represents dashboard component properties whose values are passed to the custom action function as arguments. It is a list of strings in the format `"."` (for example, `"my_selector.value`").
+- `outputs` represents dashboard component properties corresponding to the custom action function return value(s). Similar to `inputs`, it is a list of strings in the format `"."` (for example, `"my_card.children"`).
### Example of `value` as input
-The following example shows a custom action that takes the `value` of the `vm.RadioItem` and returns it inside a
-[`Card`][vizro.models.Card] component.
-!!! example "Display `value` in Card"
+The following example shows a custom action that takes the `value` of the `vm.RadioItem` and returns it inside a [`Card`][vizro.models.Card] component.
+!!! example "Display `value` in Card"
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -113,23 +109,18 @@ The following example shows a custom action that takes the `value` of the `vm.Ra
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
- === "app.yaml"
- ```yaml
- # Custom actions are currently only possible via Python configuration
- ```
- === "Result"
- [![ValueAction]][ValueAction]
- [ValueAction]: ../../assets/user_guides/custom_actions/value_as_input.png
+ === "app.yaml"
+ Custom actions are currently only possible via Python configuration.
+ === "Result"
+ [![ValueAction]][valueaction]
### Example of `clickData` as input
-The following example shows how to create a custom action that shows the `clickData` of a chart in a
-[`Card`][vizro.models.Card] component. For further information on the structure and content of the `clickData`
-property, refer to the Dash documentation on [interactive visualizations](https://dash.plotly.com/interactive-graphing).
-!!! example "Display `clickData` in Card"
+The following example shows how to create a custom action that shows the `clickData` of a chart in a [`Card`][vizro.models.Card] component. For further information on the structure and content of the `clickData` property, refer to the Dash documentation on [interactive visualizations](https://dash.plotly.com/interactive-graphing).
+!!! example "Display `clickData` in Card"
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -173,21 +164,18 @@ property, refer to the Dash documentation on [interactive visualizations](https:
```
1. Just as for any Python function, the names of the arguments `show_species` and `points_data` are arbitrary and do not need to match on to the names of `inputs` in any particular way.
- 2. We _bind_ (set) the argument `show_species` to the value `True` in the initial specification of the `function` field. These are static values that are fixed when the dashboard is _built_.
- 3. The content of `inputs` will "fill in the gaps" by setting values for the remaining unbound arguments in `my_custom_action`. Here there is one such argument, named `points_data`. Values for these are bound _dynamically at runtime_ to reflect the live state of your dashboard.
+ 1. We _bind_ (set) the argument `show_species` to the value `True` in the initial specification of the `function` field. These are static values that are fixed when the dashboard is _built_.
+ 1. The content of `inputs` will "fill in the gaps" by setting values for the remaining unbound arguments in `my_custom_action`. Here there is one such argument, named `points_data`. Values for these are bound _dynamically at runtime_ to reflect the live state of your dashboard.
+
=== "app.yaml"
- ```yaml
- # Custom actions are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomAction]][CustomAction]
+ Custom actions are currently only possible via Python configuration.
- [CustomAction]: ../../assets/user_guides/custom_actions/clickdata_as_input.png
+ === "Result"
+ [![CustomAction]][customaction]
## Multiple return values
-The return value of the custom action function is propagated to the dashboard components that are defined in the `outputs` argument of the [`Action`][vizro.models.Action] model.
-If there is a single `output` defined then the function return value is directly assigned to the component property.
-If there are multiple `outputs` defined then the return value is iterated through and each part is assigned to each component property given in `outputs` in turn. This behavior is identical to Python's flexibility in managing multiple return values.
+
+The return value of the custom action function is propagated to the dashboard components that are defined in the `outputs` argument of the [`Action`][vizro.models.Action] model. If there is a single `output` defined then the function return value is directly assigned to the component property. If there are multiple `outputs` defined then the return value is iterated through and each part is assigned to each component property given in `outputs` in turn. This behavior is identical to Python's flexibility in managing multiple return values.
!!! example "Multiple return values"
=== "app.py"
@@ -246,17 +234,17 @@ If there are multiple `outputs` defined then the return value is iterated throug
```
1. `my_custom_action` returns two values (which will be in Python tuple).
- 2. These values are assigned to the `outputs` in the same order.
- === "app.yaml"
- ```yaml
- # Custom actions are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomAction2]][CustomAction2]
+ 1. These values are assigned to the `outputs` in the same order.
- [CustomAction2]: ../../assets/user_guides/custom_actions/custom_action_multiple_return_values.png
+ === "app.yaml"
+ Custom actions are currently only possible via Python configuration.
+ === "Result"
+ [![CustomAction2]][customaction2]
!!! warning
+ Note that users of this package are responsible for the content of any custom action function that they write. Take care to avoid leaking any sensitive information or exposing to any security threat during implementation. You should always [treat the content of user input as untrusted](https://community.plotly.com/t/writing-secure-dash-apps-community-thread/54619).
- Note that users of this package are responsible for the content of any custom action function that they write - especially with regard to leaking any sensitive information or exposing to any security threat during implementation. You should always [treat the content of user input as untrusted](https://community.plotly.com/t/writing-secure-dash-apps-community-thread/54619).
+[customaction]: ../../assets/user_guides/custom_actions/clickdata_as_input.png
+[customaction2]: ../../assets/user_guides/custom_actions/custom_action_multiple_return_values.png
+[valueaction]: ../../assets/user_guides/custom_actions/value_as_input.png
diff --git a/vizro-core/docs/pages/user-guides/custom-charts.md b/vizro-core/docs/pages/user-guides/custom-charts.md
index cb26614c8..1b77d0869 100644
--- a/vizro-core/docs/pages/user-guides/custom-charts.md
+++ b/vizro-core/docs/pages/user-guides/custom-charts.md
@@ -1,9 +1,9 @@
# 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 graphs](graph.md).
+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 graphs](graph.md).
## When to use a custom chart
+
In general, you should use the custom chart decorator `@capture("graph")` if your plotly chart needs any post-update calls or customization. For example:
- You want to use any of the post figure update calls by `plotly` such as `update_layout`, `update_xaxes`, `update_traces` (for more details, see the docs on [plotly's update calls](https://plotly.com/python/creating-and-updating-figures/#other-update-methods))
@@ -12,11 +12,10 @@ In general, you should use the custom chart decorator `@capture("graph")` if you
## Steps to create a custom chart
1. Define a function that returns a `go.Figure()`.
-2. Decorate it with `@capture("graph")`.
-3. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
-4. The visualization should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments
-will not react to dashboard controls such as [`Filter`](filters.md).
-5. Pass your function to the `figure` argument of the [`Graph`][vizro.models.Graph] model.
+1. Decorate it with `@capture("graph")`.
+1. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
+1. The visualization should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments will not react to dashboard controls such as [`Filter`](filters.md).
+1. Pass your function to the `figure` argument of the [`Graph`][vizro.models.Graph] model.
The minimal example below can be used as a base to build more sophisticated charts.
@@ -39,12 +38,10 @@ To alter the data in the `data_frame` argument, consider using a [Filter](filter
## Enhanced `plotly.express` chart with reference line
-The below examples shows a case where we enhance an existing `plotly.express` chart. We add a new argument (`hline`), that is used to draw a grey reference line at the height determined by the value of `hline`. The important thing to note is that we then
-add a `Parameter` that enables the dashboard user to interact with the argument, and hence move the line in this case. See the `Result` tab for an animation.
+The below examples shows a case where we enhance an existing `plotly.express` chart. We add a new argument (`hline`), that is used to draw a grey reference line at the height determined by the value of `hline`. The important thing to note is that we then add a `Parameter` that enables the dashboard user to interact with the argument, and hence move the line in this case. See the `Result` tab for an animation.
!!! example "Custom `plotly.express` scatter chart with a `Parameter`"
=== "app.py"
-
```{.python pycafe-link}
import vizro.models as vm
import vizro.plotly.express as px
@@ -86,17 +83,14 @@ add a `Parameter` that enables the dashboard user to interact with the argument,
Vizro().build(dashboard).run()
```
- 1. Note that arguments of the custom chart can be parametrized. Here we choose to parametrize the `hline` argument (see below).
- 2. Here we parametrize the `hline` argument, but any other argument can be parametrized as well. Since there is complete flexibility regarding what can be derived from such arguments, the dashboard user has a wide range of customization options.
- === "app.yaml"
- ```yaml
- # Custom charts are currently only possible via Python configuration
- ```
- === "Result"
- [![Graph2]][Graph2]
+ 1. Note that arguments of the custom chart can be parametrized. Here we choose to parametrize the `hline` argument (see below).
+ 1. Here we parametrize the `hline` argument, but any other argument can be parametrized as well. Since there is complete flexibility regarding what can be derived from such arguments, the dashboard user has a wide range of customization options.
- [Graph2]: ../../assets/user_guides/custom_charts/custom_chart_showcase_parameter.gif
+ === "app.yaml"
+ Custom charts are currently only possible via Python configuration.
+ === "Result"
+ [![Graph2]][graph2]
## New Waterfall chart based on `go.Figure()`
@@ -104,7 +98,6 @@ The below examples shows a more involved use-case. We create and style a waterfa
!!! example "Custom `go.Figure()` waterfall chart with a `Parameter`"
=== "app.py"
-
```{.python pycafe-link}
import pandas as pd
import plotly.graph_objects as go
@@ -162,10 +155,10 @@ The below examples shows a more involved use-case. We create and style a waterfa
```
=== "app.yaml"
- ```yaml
- # Custom charts are currently only possible via Python configuration
- ```
+ Custom charts are currently only possible via Python configuration.
+
=== "Result"
- [![Graph3]][Graph3]
+ [![Graph3]][graph3]
- [Graph3]: ../../assets/user_guides/custom_charts/custom_chart_waterfall.png
+[graph2]: ../../assets/user_guides/custom_charts/custom_chart_showcase_parameter.gif
+[graph3]: ../../assets/user_guides/custom_charts/custom_chart_waterfall.png
diff --git a/vizro-core/docs/pages/user-guides/custom-css.md b/vizro-core/docs/pages/user-guides/custom-css.md
index dd2d22275..d5bc5f7dc 100755
--- a/vizro-core/docs/pages/user-guides/custom-css.md
+++ b/vizro-core/docs/pages/user-guides/custom-css.md
@@ -1,25 +1,20 @@
# Customizing Vizro dashboard CSS
-Vizro is opinionated about visual formatting, and some elements, such as the layout of the navigation and controls,
-are fixed. You can customize some settings such as background colors, fonts, and other styles via CSS overrides.
+Vizro is opinionated about visual formatting, and some elements, such as the layout of the navigation and controls, are fixed. You can customize some settings such as background colors, fonts, and other styles via CSS overrides.
To make customizations, you need to:
1. **Add a CSS file to your `assets` folder**. Refer to our user guide on [adding static assets](assets.md#how-to-add-static-assets).
-2. **Identify the correct CSS selector** for the component you want to style.
-3. **Change the relevant CSS properties** in your CSS file.
-
-
+1. **Identify the correct CSS selector** for the component you want to style.
+1. **Change the relevant CSS properties** in your CSS file.
## Introduction to Vizro CSS
+
For a short introduction to CSS, we recommend reading this article: [Get Started with CSS in 5 Minutes](https://www.freecodecamp.org/news/get-started-with-css-in-5-minutes-e0804813fc3e/).
-For a more comprehensive tutorial, refer to the [W3Schools CSS tutorial](https://www.w3schools.com/css/default.asp).
-The entire tutorial is beneficial, but the section on [CSS selectors](https://www.w3schools.com/css/css_selectors.asp)
-will be particularly useful.
+For a more comprehensive tutorial, refer to the [W3Schools CSS tutorial](https://www.w3schools.com/css/default.asp). The entire tutorial is beneficial, but the section on [CSS selectors](https://www.w3schools.com/css/css_selectors.asp) will be particularly useful.
-In Vizro, the CSS file is read in as an external stylesheet. The most common way of applying any styling to
-Vizro is therefore through the use of CSS selectors:
+In Vizro, the CSS file is read in as an external stylesheet. The most common way of applying any styling to Vizro is therefore through the use of CSS selectors:
- **Element Selector**: Applies the style to all elements inside the Vizro app.
@@ -33,8 +28,7 @@ Vizro is therefore through the use of CSS selectors:
}
```
-- **Class selector:** Targets all elements with the given class for styling. All CSS classes must be preceded with a
-`.` symbol.
+- **Class selector:** Targets all elements with the given class for styling. All CSS classes must be preceded with a `.` symbol.
```
.card {
@@ -50,30 +44,25 @@ Vizro is therefore through the use of CSS selectors:
}
```
-
## Identify the correct CSS selector
Use Chrome DevTools or a similar tool (Web Inspector, Web Developer Tools, etc.) to inspect the HTML document in your browser.
-1. **Open DevTools:** In Google Chrome, right-click on the app and select "Inspect" from the context menu. This opens the
-HTML document of your Vizro app.
+1. **Open DevTools:** In Google Chrome, right-click on the app and select "Inspect" from the context menu. This opens the HTML document of your Vizro app.
-
-2. **Select an element:** Suppose you want to change the background color of your cards. Click the
-"Select an element in the page to inspect it" icon in the top left corner of the inspect panel.
+1. **Select an element:** Suppose you want to change the background color of your cards. Click the "Select an element in the page to inspect it" icon in the top left corner of the inspect panel.
-3. **Find the HTML Block:** Hover over the component you want to style. The corresponding HTML block will be
-highlighted in the HTML document.
+1. **Find the HTML Block:** Hover over the component you want to style. The corresponding HTML block will be highlighted in the HTML document.
Notice that the selected HTML block corresponds to the container of the card and has a CSS class, here it is `card`.
-4. **Apply CSS:** Use this CSS class to style the card component. In your CSS file, you can write:
+1. **Apply CSS:** Use this CSS class to style the card component. In your CSS file, you can write:
```
.card {
@@ -83,25 +72,25 @@ highlighted in the HTML document.
This changes the background color for any HTML element with the `card` class.
-**Tip:** You can also test your CSS live by editing the CSS attributes in the "Elements" panel.
-For example, temporarily add `background: blue;`. Note that this change will be lost upon reloading the page.
+**Tip:** You can also test your CSS live by editing the CSS attributes in the "Elements" panel. For example, temporarily add `background: blue;`. Note that this change will be lost upon reloading the page.
-
## CSS overwrites
### Overwrite CSS globally
-To overwrite any global CSS property, you need to target the element selector and place your CSS file with the
-overwrites in the `assets` folder.
+
+To overwrite any global CSS property, you need to target the element selector and place your CSS file with the overwrites in the `assets` folder.
!!! example "Overwrite CSS globally"
=== "my_css_file.css"
- ```css
- h1, h2 {
- color: hotpink;
- }
- ```
+ ```css
+ h1,
+ h2 {
+ color: hotpink;
+ }
+ ```
+
=== "app.py"
```py
import os
@@ -134,44 +123,41 @@ overwrites in the `assets` folder.
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # This is an tag
+ - components:
+ - text: |
+ # This is an tag
- ## This is an tag
+ ## This is an tag
- ###### This is an tag
- type: card
- title: Changing the header color
+ ###### This is an tag
+ type: card
+ title: Changing the header color
```
- === "Result"
- [![AssetsCSS]][AssetsCSS]
-
- [AssetsCSS]: ../../assets/user_guides/assets/css_change.png
+ === "Result"
+ [![AssetsCSS]][assetscss]
### Overwrite CSS for selected pages
-To style components for a specific page, use the page's `id` in the CSS selectors. By default, this is the
-[same as the page `title`](pages.md), but such a value might not be a valid CSS identifier.
-A suitable `id` must be unique across all models in the dashboard and should contain only alphanumeric
-characters, hyphens (`-`) and underscores (`_`). In particular, note that spaces are _not_ allowed.
+To style components for a specific page, use the page's `id` in the CSS selectors. By default, this is the [same as the page `title`](pages.md), but such a value might not be a valid CSS identifier.
+
+A suitable `id` must be unique across all models in the dashboard and should contain only alphanumeric characters, hyphens (`-`) and underscores (`_`). In particular, note that spaces are _not_ allowed.
Suppose you want to hide the page title on one page only. Here's how you can achieve this:
1. Give a valid `id` to the `Page`, for example `Page(id="page-with-hidden-title", title="Page with hidden title", ...)`.
-2. Identify the CSS class or CSS `id` you need to target. To hide the page title, you need to hide the parent container with the id `right-header`.
-3. Use the `id` to hide the content.
-4. Add your custom css file to the `assets` folder.
-
+1. Identify the CSS class or CSS `id` you need to target. To hide the page title, you need to hide the parent container with the id `right-header`.
+1. Use the `id` to hide the content.
+1. Add your custom css file to the `assets` folder.
!!! example "Hide page title on selected pages"
=== "my_css_file.css"
- ```css
- #page-with-hidden-title #right-header {
- display: none;
- }
- ```
+ ```css
+ #page-with-hidden-title #right-header {
+ display: none;
+ }
+ ```
+
=== "app.py"
```py
import vizro.models as vm
@@ -199,25 +185,24 @@ Suppose you want to hide the page title on one page only. Here's how you can ach
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Placeholder
- type: card
- title: Page with hidden title
- id: page-with-hidden-title
- - components:
- - text: |
- # Placeholder
- type: card
- title: Page with shown title
+ - components:
+ - text: |
+ # Placeholder
+ type: card
+ title: Page with hidden title
+ id: page-with-hidden-title
+ - components:
+ - text: |
+ # Placeholder
+ type: card
+ title: Page with shown title
```
- === "Result"
- [![PageTitle]][PageTitle]
-
- [PageTitle]: ../../assets/user_guides/assets/css_page_title.png
+ === "Result"
+ [![PageTitle]][pagetitle]
### Overwrite CSS for selected components
+
To adjust CSS properties for specific components, such as altering the appearance of a selected [`Card`][vizro.models.Card] rather than all Cards, you need to supply an `id` to the component you want to style.
Let's say we want to change the `background-color` and `color` of a specific `Card`.
@@ -225,41 +210,43 @@ Let's say we want to change the `background-color` and `color` of a specific `Ca
Here's how you can do it:
1. Assign a unique `id` to the relevant `Card`, for example: `Card(id="custom-card", ...)`
-2. Run your dashboard and open it in your browser
-3. View the HTML document to find the appropriate CSS class or element you need to target, as explained in the section
-on [identifying the correct CSS selector](#identify-the-correct-css-selector).
+1. Run your dashboard and open it in your browser
+1. View the HTML document to find the appropriate CSS class or element you need to target, as explained in the section on [identifying the correct CSS selector](#identify-the-correct-css-selector).
-It's essential to understand the relationship between the targeted CSS class or element and the component assigned
-`id`, for example:
+It's essential to understand the relationship between the targeted CSS class or element and the component assigned `id`, for example:
-```html title="HTML structure of a `Card`"
+
+```html title="HTML structure of a card"
-
- Lorem ipsum dolor sit amet consectetur adipisicing elit.
-
+
+
+ Lorem ipsum dolor sit amet consectetur adipisicing elit.
+
+
```
-
-* **Main element with `id`:** There is a `` with our `id="custom-card"`.
-* **Parent element:** That `` is wrapped inside a parent `` with the class name `"card"`. This is the element we need to target to change the background color.
-* **Child element:** The card text is wrapped inside a `` that is a child of the `
` with our `id`. This is the element we need to target to change the font color.
+
+- **Main element with `id`:** There is a `` with our `id="custom-card"`.
+- **Parent element:** That `` is wrapped inside a parent `` with the class name `"card"`. This is the element we need to target to change the background color.
+- **Child element:** The card text is wrapped inside a `` that is a child of the `
` with our `id`. This is the element we need to target to change the font color.
!!! example "Customizing CSS properties in selective components"
=== "my_css_file.css"
- ```css
- /* Apply styling to parent */
- .card:has(#custom-card) {
- background-color: white;
- }
+ ```css
+ /* Apply styling to parent */
+ .card:has(#custom-card) {
+ background-color: white;
+ }
+
+ /* Apply styling to child */
+ #custom-card p {
+ color: black;
+ }
+ ```
- /* Apply styling to child */
- #custom-card p {
- color: black;
- }
- ```
=== "app.py"
```py
import vizro.models as vm
@@ -285,77 +272,65 @@ It's essential to understand the relationship between the targeted CSS class or
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- Lorem ipsum dolor sit amet consectetur adipisicing elit.
- type: card
- id: custom-card
- - text: |
- Lorem ipsum dolor sit amet consectetur adipisicing elit.
- type: card
- title: Changing the card color
+ - components:
+ - text: |
+ Lorem ipsum dolor sit amet consectetur adipisicing elit.
+ type: card
+ id: custom-card
+ - text: |
+ Lorem ipsum dolor sit amet consectetur adipisicing elit.
+ type: card
+ title: Changing the card color
```
- === "Result"
- [![CardCSS]][CardCSS]
-
- [CardCSS]: ../../assets/user_guides/assets/css_change_card.png
+ === "Result"
+ [![CardCSS]][cardcss]
!!! note "Relationship between model ID and CSS ID"
+ Some Vizro components produce a single HTML element with an ID that matches the model ID, allowing you to target it directly using the CSS #id selector. Other components generate multiple HTML elements. Within these, the "core" element will have an ID matching the model ID, while non-core elements may have IDs that are variations of it, such as `{model-id}-title`.
- Some Vizro components produce a single HTML element with an ID that matches the model ID, allowing you to target it
- directly using the CSS #id selector. Other components generate multiple HTML elements. Within these, the "core"
- element will have an ID matching the model ID, while non-core elements may have IDs that are variations of it,
- such as `{model-id}-title`.
-
- In all instances, you can determine the correct selector by using Chrome DevTools or a similar tool after setting the
- appropriate model ID.
-
+ In all instances, you can determine the correct selector by using Chrome DevTools or a similar tool after setting the appropriate model ID.
## Common examples
### Make your CSS responsive to theme switches with variables
-To ensure your CSS adapts to theme changes, we recommend using CSS variables (`var`) whenever possible. For a
-comprehensive list of available variable names, refer to the
-[Bootstrap documentation](https://getbootstrap.com/docs/5.3/customize/css-variables/). Note that our
-Bootstrap stylesheet is still under development, so not all Bootstrap variables are currently available.
-Additionally, you can define your own CSS variables, as demonstrated in the example on
-[changing the container background color](#change-the-styling-of-a-container).
+
+To ensure your CSS adapts to theme changes, we recommend using CSS variables (`var`) whenever possible. For a comprehensive list of available variable names, refer to the [Bootstrap documentation](https://getbootstrap.com/docs/5.3/customize/css-variables/). Note that our Bootstrap stylesheet is still under development, so not all Bootstrap variables are currently available. Additionally, you can define your own CSS variables, as demonstrated in the example on [changing the container background color](#change-the-styling-of-a-container).
### Turn off page title
+
See the example above on [hiding the page title on selected pages](#overwrite-css-for-selected-pages).
### Change the background color of a card
+
See the example above on [customizing CSS properties in selective components](#overwrite-css-for-selected-components).
### Change the global font
+
The default fonts for a Vizro app are `Inter, sans-serif, Arial, serif`.
If you need to change the global font, perhaps to adhere to branding guidelines, follow these steps:
1. Download the desired font from a font provider such as [Google Fonts](https://fonts.google.com/).
-2. Place the font file (`.ttf`, `woff2`, etc.) into your `assets` folder. Here’s an example of what the assets folder might look like:
- 
+1. Place the font file (`.ttf`, `woff2`, etc.) into your `assets` folder. Here’s an example of what the assets folder might look like:
-3. Add the font to your CSS file using the `@font-face` rule and apply the font globally to your Vizro app, making sure
-to specify fallback fonts. Add the following to your `custom.css` file:
+ 
+1. Add the font to your CSS file using the `@font-face` rule and apply the font globally to your Vizro app, making sure to specify fallback fonts. Add the following to your `custom.css` file:
```css
@font-face {
- font-family: PlayfairDisplay;
- src: url("PlayfairDisplay-VariableFont_wght.ttf") format("truetype");
+ font-family: PlayfairDisplay;
+ src: url("PlayfairDisplay-VariableFont_wght.ttf") format("truetype");
}
* {
- font-family: PlayfairDisplay, Inter, sans-serif, Arial, serif;
+ font-family: PlayfairDisplay, Inter, sans-serif, Arial, serif;
}
```
-
-4. Note that the modification above applies solely to the dashboard font. To also change the font within the
-Plotly charts, you must specify this at the beginning of your `app.py` file:
+1. Note that the modification above applies solely to the dashboard font. To also change the font within the Plotly charts, you must specify this at the beginning of your `app.py` file:
```python
import plotly.io as pio
@@ -365,44 +340,42 @@ Plotly charts, you must specify this at the beginning of your `app.py` file:
```
### Reposition the logo
-By default, the logo appears in the top left corner of the dashboard. You can move it further to the left or right by
-adjusting the `padding` of the `#page-header` element. Here is an example of how to achieve this:
+
+By default, the logo appears in the top left corner of the dashboard. You can move it further to the left or right by adjusting the `padding` of the `#page-header` element. Here is an example of how to achieve this:
```css
#page-header {
- padding-left: 8px;
+ padding-left: 8px;
}
```
-
### Change the styling of a container
-If you want to make the subsections of your dashboard stand out more, you can do this by placing your components
-inside a [Container](container.md) and changing the container's styling, for example, background color, borders, padding, etc.
-To do this, you need to change the container's CSS class. Using the DevTool, as explained in the section on
-[identifying the correct CSS selector](#identify-the-correct-css-selector), you'll find that the CSS class for the
-`Container` is `page-component-container`. You can then use this class to set a new `background-color` and `padding`.
+If you want to make the subsections of your dashboard stand out more, you can do this by placing your components inside a [Container](container.md) and changing the container's styling, for example, background color, borders, padding, etc.
+
+To do this, you need to change the container's CSS class. Using the DevTool, as explained in the section on [identifying the correct CSS selector](#identify-the-correct-css-selector), you'll find that the CSS class for the `Container` is `page-component-container`. You can then use this class to set a new `background-color` and `padding`.
!!! example "Style a container"
=== "custom.css"
- ```css
- /* Assign a variable to the dark and light theme */
- [data-bs-theme="dark"] {
- --container-bg-color: #232632;
- }
-
- [data-bs-theme="light"] {
- --container-bg-color: #F5F6F6;
- }
+ ```css
+ /* Assign a variable to the dark and light theme */
+ [data-bs-theme="dark"] {
+ --container-bg-color: #232632;
+ }
+
+ [data-bs-theme="light"] {
+ --container-bg-color: #F5F6F6;
+ }
+
+ /* Use the custom variable var(--container-bg-color) */
+ .page-component-container {
+ background: var(--container-bg-color);
+ padding: 12px;
+ }
+ ```
- /* Use the custom variable var(--container-bg-color) */
- .page-component-container {
- background: var(--container-bg-color);
- padding: 12px;
- }
- ```
=== "app.py"
```py
import vizro.models as vm
@@ -437,12 +410,12 @@ To do this, you need to change the container's CSS class. Using the DevTool, as
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - title: "Page with subsections"
+ - title: Page with subsections
layout:
grid: [[0, 1]]
components:
- type: container
- title: "Container I"
+ title: Container I
components:
- type: graph
figure:
@@ -452,7 +425,7 @@ To do this, you need to change the container's CSS class. Using the DevTool, as
y: sepal_length
color: species
- type: container
- title: "Container II"
+ title: Container II
components:
- type: graph
figure:
@@ -462,13 +435,11 @@ To do this, you need to change the container's CSS class. Using the DevTool, as
y: sepal_length
color: species
```
- === "Result"
- [![StyleContainer]][StyleContainer]
- [StyleContainer]: ../../assets/user_guides/custom_css/style-container.png
+ === "Result"
+ [![StyleContainer]][stylecontainer]
-You will notice that the background colors of the charts are different. To align it with the colors of the container,
-you can make the charts' background transparent.
+You will notice that the background colors of the charts are different. To align it with the colors of the container, you can make the charts' background transparent.
To make the background of all charts transparent:
@@ -492,3 +463,8 @@ def custom_chart(data_frame):
```
+
+[assetscss]: ../../assets/user_guides/assets/css_change.png
+[cardcss]: ../../assets/user_guides/assets/css_change_card.png
+[pagetitle]: ../../assets/user_guides/assets/css_page_title.png
+[stylecontainer]: ../../assets/user_guides/custom_css/style-container.png
diff --git a/vizro-core/docs/pages/user-guides/custom-figures.md b/vizro-core/docs/pages/user-guides/custom-figures.md
index f135127be..3a178932f 100644
--- a/vizro-core/docs/pages/user-guides/custom-figures.md
+++ b/vizro-core/docs/pages/user-guides/custom-figures.md
@@ -1,41 +1,36 @@
# How to create custom figures
-This guide explains how to create custom figures, which is useful when you need a component that reacts to
-[filter](filters.md) and [parameter](parameters.md) controls.
+This guide explains how to create custom figures, which is 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).
## When to use a custom figure
-As described in the flowchart detailing [when to use `Figure`](figure.md), custom figures should be used if
-**both** of the following conditions are met:
+
+As described in the flowchart detailing [when to use `Figure`](figure.md), custom figures should be used if **both** of the following conditions are met:
- You need a figure that doesn't fit into the existing pre-defined components ([`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid]).
- You need a figure that isn't available in our pre-defined figure functions [`vizro.figures`](../API-reference/figure-callables.md).
## Steps to create a custom figure
-1. Define a function that returns a [Dash component](https://dash.plotly.com/#open-source-component-libraries).
-This can, but does not need to, be based on code in our pre-defined figure functions in [`vizro.figures`](../API-reference/figure-callables.md).
-2. Decorate it with `@capture("figure")`.
-3. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
-4. The figure should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments
-will not react to dashboard controls such as [`Filter`](filters.md).
-5. Pass your function to the `figure` argument of the [`Figure`][vizro.models.Figure] model.
+1. Define a function that returns a [Dash component](https://dash.plotly.com/#open-source-component-libraries). This can, but does not need to, be based on code in our pre-defined figure functions in [`vizro.figures`](../API-reference/figure-callables.md).
+1. Decorate it with `@capture("figure")`.
+1. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
+1. The figure should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments will not react to dashboard controls such as [`Filter`](filters.md).
+1. Pass your function to the `figure` argument of the [`Figure`][vizro.models.Figure] model.
The following examples can be used as a base to build more sophisticated figures.
## Examples of custom figures
### Custom KPI card
-To change the design or content of our existing KPI (key performance indicator) cards from
-[`vizro.figures`](../API-reference/figure-callables.md), you can do so by following the steps described above.
-For instance, to make a KPI card with the icon positioned on the right side of the title instead of the left,
-copy and paste the [source code of `kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card) and
-adjust the return statement of the function.
+To change the design or content of our existing KPI (key performance indicator) cards from [`vizro.figures`](../API-reference/figure-callables.md), you can do so by following the steps described above.
+
+For instance, to make a KPI card with the icon positioned on the right side of the title instead of the left, copy and paste the [source code of `kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card) and adjust the return statement of the function.
+
!!! example "Custom KPI card"
=== "app.py"
```{.python pycafe-link}
@@ -107,29 +102,26 @@ adjust the return statement of the function.
```
1. Here we decorate our custom figure function with the `@capture("figure")` decorator.
- 2. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
- 3. We adjust the return statement to include the icon on the right side of the title. This is achieved by swapping the order of the `html.H2` and `html.P` compared to the original `kpi_card`.
- 4. This creates a [`layout`](layouts.md) with four rows and columns. The KPI cards are positioned in the first two cells, while the remaining cells are empty.
- 5. For more information, refer to the API reference for the [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card).
- 6. Our custom figure function `custom_kpi_card` now needs to be passed on to the `vm.Figure`.
+ 1. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
+ 1. We adjust the return statement to include the icon on the right side of the title. This is achieved by swapping the order of the `html.H2` and `html.P` compared to the original `kpi_card`.
+ 1. This creates a [`layout`](layouts.md) with four rows and columns. The KPI cards are positioned in the first two cells, while the remaining cells are empty.
+ 1. For more information, refer to the API reference for the [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card).
+ 1. Our custom figure function `custom_kpi_card` now needs to be passed on to the `vm.Figure`.
=== "app.yaml"
- ```yaml
- # Custom figures are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomKPI]][CustomKPI]
+ Custom figures are currently only possible via Python configuration.
- [CustomKPI]: ../../assets/user_guides/figure/custom_kpi.png
+ === "Result"
+ [![CustomKPI]][customkpi]
### Dynamic HTML header
-You can create a custom figure for any [Dash component](https://dash.plotly.com/#open-source-component-libraries).
-Below is an example of a custom figure that returns a `html.H2` component that dynamically updates based on the selected
-name from a filter.
+
+You can create a custom figure for any [Dash component](https://dash.plotly.com/#open-source-component-libraries). Below is an example of a custom figure that returns a `html.H2` component that dynamically updates based on the selected name from a filter.
+
!!! example "Dynamic HTML header"
=== "app.py"
```{.python pycafe-link}
@@ -159,27 +151,24 @@ name from a filter.
```
1. Here we decorate our custom figure function with the `@capture("figure")` decorator.
- 2. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
- 3. We return a `html.H2` component that dynamically updates based on the selected name from the filter.
- 4. Our custom figure function `dynamic_html_header` now needs to be passed on to the `vm.Figure`.
+ 1. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
+ 1. We return a `html.H2` component that dynamically updates based on the selected name from the filter.
+ 1. Our custom figure function `dynamic_html_header` now needs to be passed on to the `vm.Figure`.
=== "app.yaml"
- ```yaml
- # Custom figures are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomHTML]][CustomHTML]
+ Custom figures are currently only possible via Python configuration.
- [CustomHTML]: ../../assets/user_guides/figure/custom_html.png
+ === "Result"
+ [![CustomHTML]][customhtml]
-
### Dynamic number of cards
-The example below shows how to create multiple cards created from a `pandas.DataFrame` where the
-number of cards displayed dynamically adjusts based on a `vm.Parameter`.
+
+The example below shows how to create multiple cards created from a `pandas.DataFrame` where the number of cards displayed dynamically adjusts based on a `vm.Parameter`.
+
!!! example "Dynamic number of cards"
=== "app.py"
```py
@@ -239,40 +228,39 @@ number of cards displayed dynamically adjusts based on a `vm.Parameter`.
```
1. Here we decorate our custom figure function with the `@capture("figure")` decorator.
- 2. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
- 3. Our decorated figure function `multiple_cards` now needs to be passed on to the `vm.Figure`.
- 4. We add a [`vm.Parameter`](parameters.md) to dynamically adjust the number of cards displayed.
- The parameter targets the `n_rows` argument of the `multiple_cards` function, determining the number of rows
- taken from the data.
+ 1. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
+ 1. Our decorated figure function `multiple_cards` now needs to be passed on to the `vm.Figure`.
+ 1. We add a [`vm.Parameter`](parameters.md) to dynamically adjust the number of cards displayed. The parameter targets the `n_rows` argument of the `multiple_cards` function, determining the number of rows taken from the data.
Run and edit this code in PyCafe
=== "styling.css"
```css
.multiple-cards-container {
- display: flex;
- flex-wrap: wrap;
- gap: 12px;
+ display: flex;
+ flex-wrap: wrap;
+ gap: 12px;
}
.figure-container {
- height: unset;
- width: unset;
+ height: unset;
+ width: unset;
}
.figure-container .card {
- height: 210px;
- width: 240px;
+ height: 210px;
+ width: 240px;
}
```
- === "app.yaml"
- ```yaml
- # Custom figures are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomFigure]][CustomFigure]
- [CustomFigure]: ../../assets/user_guides/figure/custom_multiple_cards.png
+ === "app.yaml"
+ Custom figures are currently only possible via Python configuration.
+ === "Result"
+ [![CustomFigure]][customfigure]
+
+[customfigure]: ../../assets/user_guides/figure/custom_multiple_cards.png
+[customhtml]: ../../assets/user_guides/figure/custom_html.png
+[customkpi]: ../../assets/user_guides/figure/custom_kpi.png
diff --git a/vizro-core/docs/pages/user-guides/custom-tables.md b/vizro-core/docs/pages/user-guides/custom-tables.md
index e990cfbb0..42748820b 100644
--- a/vizro-core/docs/pages/user-guides/custom-tables.md
+++ b/vizro-core/docs/pages/user-guides/custom-tables.md
@@ -1,21 +1,18 @@
# How to create custom Dash AG Grids and Dash DataTables
-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.
+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.
-The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] model accept the `figure` argument, where you can enter
-_any_ [`dash_ag_grid`][vizro.tables.dash_ag_grid] or [`dash_data_table`][vizro.tables.dash_data_table] chart as explained in the [user guide on tables](table.md).
+The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] model accept the `figure` argument, where you can enter _any_ [`dash_ag_grid`][vizro.tables.dash_ag_grid] or [`dash_data_table`][vizro.tables.dash_data_table] chart as explained in the [user guide on tables](table.md).
One reason could be that you want to create a table/grid that requires computations that can be controlled by parameters (see the example below).
### Steps to create a custom table
1. Define a function that returns a `dash_ag_grid.AgGrid` or `dash_table.DataTable` object.
-2. Decorate it with `@capture("ag_grid")` or `@capture("table")`.
-3. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
-4. The table should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments
-will not react to dashboard controls such as [`Filter`](filters.md).
-5. Pass your function to the `figure` argument of the [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid] model.
+1. Decorate it with `@capture("ag_grid")` or `@capture("table")`.
+1. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
+1. The table should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments will not react to dashboard controls such as [`Filter`](filters.md).
+1. Pass your function to the `figure` argument of the [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid] model.
The following examples show a possible version of a custom table. In this case the argument `chosen_columns` was added, which you can control with a parameter:
@@ -70,14 +67,12 @@ The following examples show a possible version of a custom table. In this case t
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
- ```yaml
- # Custom tables are currently only possible via Python configuration
- ```
- === "Result"
- [![Table3]][Table3]
+ Custom tables are currently only possible via Python configuration.
- [Table3]: ../../assets/user_guides/table/custom_table.png
+ === "Result"
+ [![Table3]][table3]
??? example "Custom Dash AgGrid"
=== "app.py"
@@ -136,11 +131,12 @@ The following examples show a possible version of a custom table. In this case t
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
- ```yaml
- # Custom Ag Grids are currently only possible via Python configuration
- ```
+ Custom Ag Grids are currently only possible via Python configuration.
+
=== "Result"
- [![GridCustom]][GridCustom]
+ [![GridCustom]][gridcustom]
- [GridCustom]: ../../assets/user_guides/table/custom_grid.png
+[gridcustom]: ../../assets/user_guides/table/custom_grid.png
+[table3]: ../../assets/user_guides/table/custom_table.png
diff --git a/vizro-core/docs/pages/user-guides/dashboard.md b/vizro-core/docs/pages/user-guides/dashboard.md
index 0b37e03fa..244f65256 100644
--- a/vizro-core/docs/pages/user-guides/dashboard.md
+++ b/vizro-core/docs/pages/user-guides/dashboard.md
@@ -1,16 +1,15 @@
# How to create a dashboard
-This guide shows you how to configure and call a [`Dashboard`][vizro.models.Dashboard] using either
-pydantic models, Python dictionaries, YAML, or JSON.
+
+This guide shows you how to configure and call a [`Dashboard`][vizro.models.Dashboard] using either pydantic models, Python dictionaries, YAML, or JSON.
To create a dashboard:
1. Choose one of the possible configuration syntaxes
-2. Create your `pages`, see our [guide on Pages](pages.md)
-3. (optional) Choose a `theme`, see our [guide on Themes](themes.md)
-4. (optional) Customize your `navigation`, see our [guide on Navigation](navigation.md)
-5. (optional) Set a `title` for your dashboard
-6. Add your `dashboard` to the `build` call of Vizro
-
+1. Create your `pages`, see our [guide on Pages](pages.md)
+1. (optional) Choose a `theme`, see our [guide on Themes](themes.md)
+1. (optional) Customize your `navigation`, see our [guide on Navigation](navigation.md)
+1. (optional) Set a `title` for your dashboard
+1. Add your `dashboard` to the `build` call of Vizro
## Use dashboard configuration options
@@ -37,6 +36,7 @@ To create a dashboard:
Vizro().build(dashboard).run()
```
+
=== "app.py - Python dict"
```py
import vizro.plotly.express as px
@@ -77,6 +77,7 @@ To create a dashboard:
Vizro().build(dashboard).run()
```
+
=== "dashboard.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -101,50 +102,49 @@ To create a dashboard:
type: filter
title: My first dashboard
```
+
=== "dashboard.json"
```json
{
- "pages": [
+ "pages": [
+ {
+ "components": [
+ {
+ "figure": {
+ "_target_": "scatter",
+ "color": "species",
+ "data_frame": "iris",
+ "x": "sepal_length",
+ "y": "petal_width"
+ },
+ "type": "graph"
+ },
{
- "components": [
- {
- "figure": {
- "_target_": "scatter",
- "color": "species",
- "data_frame": "iris",
- "x": "sepal_length",
- "y": "petal_width"
- },
- "type": "graph"
- },
- {
- "figure": {
- "_target_": "histogram",
- "color": "species",
- "data_frame": "iris",
- "x": "sepal_width",
- },
- "type": "graph"
- }
- ],
- "controls": [
- {
- "column": "species",
- "type": "filter"
- }
- ],
- "title": "My first dashboard"
+ "figure": {
+ "_target_": "histogram",
+ "color": "species",
+ "data_frame": "iris",
+ "x": "sepal_width"
+ },
+ "type": "graph"
}
- ]
+ ],
+ "controls": [
+ {
+ "column": "species",
+ "type": "filter"
+ }
+ ],
+ "title": "My first dashboard"
+ }
+ ]
}
```
- === "Result"
- [![Dashboard]][Dashboard]
- [Dashboard]: ../../assets/user_guides/dashboard/dashboard.png
+ === "Result"
+ [![Dashboard]][dashboard]
!!! note "Extra `.py` files for `yaml` and `json` required"
-
Note that in the `yaml` and `json` example an extra `.py` is required to register the data and parse the yaml/json configuration.
=== "app.py for yaml"
@@ -164,6 +164,7 @@ To create a dashboard:
Vizro().build(dashboard).run()
```
+
=== "app.py for json"
```py
import json
@@ -187,7 +188,6 @@ After running the dashboard, you can access the dashboard via `localhost:8050`.
If supplied, the `title` of the [`Dashboard`][vizro.models.Dashboard] displays a heading at the top of every page.
-
## Add a dashboard logo
Vizro will [automatically incorporate the dashboard logo](assets.md/#add-a-logo-image) in the top-left corner of each page if an image named `logo.` is present within the assets folder.
@@ -196,11 +196,10 @@ Vizro will [automatically incorporate the dashboard logo](assets.md/#add-a-logo-
## Browser title
-The [website icon](assets.md/#change-the-favicon), Dashboard `title` (if supplied) and [Page `title`][vizro.models.Page] are displayed in the browser's
-title bar. For example, if your Dashboard `title` is "Vizro Demo" and the Page `title` is "Homepage", then the title in the browser tab will be "Vizro Demo: Homepage".
+The [website icon](assets.md/#change-the-favicon), Dashboard `title` (if supplied) and [Page `title`][vizro.models.Page] are displayed in the browser's title bar. For example, if your Dashboard `title` is "Vizro Demo" and the Page `title` is "Homepage", then the title in the browser tab will be "Vizro Demo: Homepage".
## Meta tags for social media
-Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat
-clients. The preview includes the `URL`, `title`, plus an [image](assets.md/#include-a-meta-tags-image) and
-[Page `description`][vizro.models.Page] (if supplied). To see an example, try sharing an example from the [Vizro examples gallery](https://vizro.mckinsey.com/).
+Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat clients. The preview includes the `URL`, `title`, plus an [image](assets.md/#include-a-meta-tags-image) and [Page `description`][vizro.models.Page] (if supplied). To see an example, try sharing an example from the [Vizro examples gallery](https://vizro.mckinsey.com/).
+
+[dashboard]: ../../assets/user_guides/dashboard/dashboard.png
diff --git a/vizro-core/docs/pages/user-guides/data.md b/vizro-core/docs/pages/user-guides/data.md
index 51bf84b97..d19b8aafb 100644
--- a/vizro-core/docs/pages/user-guides/data.md
+++ b/vizro-core/docs/pages/user-guides/data.md
@@ -2,11 +2,12 @@
Vizro supports two different types of data:
-* [Static data](#static-data): pandas DataFrame. This is the simplest method and best to use if you do not need the more advanced functionality of dynamic data.
-* [Dynamic data](#dynamic-data): function that returns a pandas DataFrame. This is a bit more complex to understand but has more advanced functionality such as the ability to refresh data while the dashboard is running.
+- [Static data](#static-data): pandas DataFrame. This is the simplest method and best to use if you do not need the more advanced functionality of dynamic data.
+- [Dynamic data](#dynamic-data): function that returns a pandas DataFrame. This is a bit more complex to understand but has more advanced functionality such as the ability to refresh data while the dashboard is running.
The following flowchart shows what you need to consider when choosing how to set up your data.
-``` mermaid
+
+```mermaid
graph TD
refresh["`Do you need your data to refresh while the dashboard is running?`"]
specification["`Do you need to specify your dashboard through a configuration language like YAML?`"]
@@ -27,11 +28,10 @@ graph TD
```
??? note "Static vs. dynamic data comparison"
-
This table gives a full comparison between static and dynamic data. Do not worry if you do not yet understand everything in it; it will become clearer after reading more about [static data](#static-data) and [dynamic data](#dynamic-data)!
| | Static | Dynamic |
- |---------------------------------------------------------------|------------------|------------------------------------------|
+ | ------------------------------------------------------------- | ---------------- | ---------------------------------------- |
| Required Python type | pandas DataFrame | Function that returns a pandas DataFrame |
| Can be supplied directly in `data_frame` argument of `figure` | Yes | No |
| Can be referenced by name after adding to data manager | Yes | Yes |
@@ -73,14 +73,13 @@ The below example uses the Iris data saved to a file `iris.csv` in the same dire
```
1. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
- === "Result"
- [![DataBasic]][DataBasic]
- [DataBasic]: ../../assets/user_guides/data/data_pandas_dataframe.png
+ === "Result"
+ [![DataBasic]][databasic]
The [`Graph`][vizro.models.Graph], [`AgGrid`][vizro.models.AgGrid] and [`Table`][vizro.models.Table] models all have an argument called `figure`. This accepts a function (in the above example, `px.scatter`) that takes a pandas DataFrame as its first argument. The name of this argument is always `data_frame`. When configuring the dashboard using Python, it is optional to give the name of the argument: if you like, you could write `data_frame=iris` instead of `iris`.
-!!! note
+!!! note
With static data, once the dashboard is running, the data shown in the dashboard cannot change even if the source data in `iris.csv` changes. The code `iris = pd.read_csv("iris.csv")` is only executed once when the dashboard is first started. If you would like changes to source data to flow through to the dashboard then you must use [dynamic data](#dynamic-data).
### Reference by name
@@ -107,27 +106,27 @@ If you would like to specify your dashboard configuration through YAML then you
```
1. `"iris"` is the name of a data source added to the data manager. This data is a pandas DataFrame created by reading from the CSV file `iris.csv`.
+
=== "dashboard.yaml"
```yaml
pages:
- - components:
- - figure:
+ - components:
+ figure:
_target_: box
data_frame: iris # (1)!
x: species
y: petal_width
color: species
type: graph
- title: Static data example
+ title: Static data example
```
1. Refer to the `"iris"` data source in the data manager.
- === "Result"
- [![DataBasic]][DataBasic]
- [DataBasic]: ../../assets/user_guides/data/data_pandas_dataframe.png
+ === "Result"
+ [![DataBasic]][databasic]
-It is also possible to refer to a named data source using the Python API: `px.scatter("iris", ...)` or `px.scatter(data_frame="iris", ...)` would work if the `"iris"` data source has been registered in the data manager.
+It is also possible to refer to a named data source using the Python API: `px.scatter("iris", ...)` or `px.scatter(data_frame="iris", ...)` would work if the `"iris"` data source has been registered in the data manager.
## Dynamic data
@@ -166,14 +165,12 @@ The example below shows how data is fetched dynamically every time the page is r
```
1. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
- 2. To demonstrate that dynamic data can change when the page is refreshed, select 50 points at random. This simulates what would happen if your file `iris.csv` were constantly changing.
- 3. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()`; doing so would result in static data that cannot be reloaded.
- 4. Dynamic data is referenced by the name of the data source `"iris"`.
+ 1. To demonstrate that dynamic data can change when the page is refreshed, select 50 points at random. This simulates what would happen if your file `iris.csv` were constantly changing.
+ 1. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()`; doing so would result in static data that cannot be reloaded.
+ 1. Dynamic data is referenced by the name of the data source `"iris"`.
=== "Result"
- [![DynamicData]][DynamicData]
-
- [DynamicData]: ../../assets/user_guides/data/dynamic_data.gif
+ [![DynamicData]][dynamicdata]
Since dynamic data sources must always be added to the data manager and referenced by name, they may be used in YAML configuration [exactly the same way as for static data sources](#reference-by-name).
@@ -184,10 +181,10 @@ By default, a dynamic data function executes every time the dashboard is refresh
The Vizro data manager has a server-side caching mechanism to help solve this. Vizro's cache uses [Flask-Caching](https://flask-caching.readthedocs.io/en/latest/), which supports a number of possible cache backends and [configuration options](https://flask-caching.readthedocs.io/en/latest/#configuring-flask-caching). By default, the cache is turned off.
+
In a development environment the easiest way to enable caching is to use a [simple memory cache](https://cachelib.readthedocs.io/en/stable/simple/) with the default configuration options. This is achieved by adding one line to the above example to set `data_manager.cache`:
!!! example "Simple cache with default timeout of 5 minutes"
-
```py hl_lines="13"
from flask_caching import Cache
from vizro import Vizro
@@ -225,7 +222,6 @@ data_manager.cache = Cache(config={"CACHE_TYPE": "SimpleCache", "CACHE_DEFAULT_T
```
!!! warning
-
Simple cache exists purely for single-process development purposes and is not intended to be used in production. If you deploy with multiple workers, [for example with Gunicorn](run.md/#gunicorn), then you should use a production-ready cache backend. All of Flask-Caching's [built-in backends](https://flask-caching.readthedocs.io/en/latest/#built-in-cache-backends) other than `SimpleCache` are suitable for production. In particular, you might like to use [`FileSystemCache`](https://cachelib.readthedocs.io/en/stable/file/) or [`RedisCache`](https://cachelib.readthedocs.io/en/stable/redis/):
```py title="Production-ready caches"
@@ -239,7 +235,9 @@ data_manager.cache = Cache(config={"CACHE_TYPE": "SimpleCache", "CACHE_DEFAULT_T
Since Flask-Caching relies on [`pickle`](https://docs.python.org/3/library/pickle.html), which can execute arbitrary code during unpickling, you should not cache data from untrusted sources. Doing so [could be unsafe](https://github.com/pallets-eco/flask-caching/pull/209).
Note that when a production-ready cache backend is used, the cache is persisted beyond the Vizro process and is not cleared by restarting your server. To clear the cache then you must do so manually, for example, if you use `FileSystemCache` then you would delete your `cache` directory. Persisting the cache can also be useful for development purposes when handling data that takes a long time to load: even if you do not need the data to refresh while your dashboard is running, it can speed up your development loop to use dynamic data with a cache that is persisted between repeated runs of Vizro.
+
+
#### Set timeouts
You can change the timeout of the cache independently for each dynamic data source in the data manager using the `timeout` setting (measured in seconds). A `timeout` of 0 indicates that the cache does not expire. This is effectively the same as using [static data](#static-data).
@@ -278,8 +276,8 @@ In general, a parametrized dynamic data source should always return a pandas Dat
To add a parameter to control a dynamic data source, do the following:
1. add the appropriate argument to your dynamic data function and specify a default value for the argument.
-2. give an `id` to all components that have the data source you wish to alter through a parameter.
-3. [add a parameter](parameters.md) with `targets` of the form `.data_frame.` and a suitable [selector](selectors.md).
+1. give an `id` to all components that have the data source you wish to alter through a parameter.
+1. [add a parameter](parameters.md) with `targets` of the form `.data_frame.` and a suitable [selector](selectors.md).
For example, let us extend the [dynamic data example](#dynamic-data) above into an example of how parametrized dynamic data works. The `load_iris_data` can take an argument `number_of_points` controlled from the dashboard with a [`Slider`][vizro.models.Slider].
@@ -318,21 +316,18 @@ For example, let us extend the [dynamic data example](#dynamic-data) above into
```
1. `load_iris_data` takes a single argument, `number_of_points`, with a default value of 10.
- 2. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
- 3. Sample points at random, where `number_of_points` gives the number of points selected.
- 4. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()` or `load_iris_data(number_of_points=...)`; doing so would result in static data that cannot be reloaded.
- 5. Give the `vm.Graph` component `id="graph"` so that the `vm.Parameter` can target it. Dynamic data is referenced by the name of the data source `"iris"`.
- 6. Create a `vm.Parameter` to target the `number_of_points` argument for the `data_frame` used in `graph`.
+ 1. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
+ 1. Sample points at random, where `number_of_points` gives the number of points selected.
+ 1. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()` or `load_iris_data(number_of_points=...)`; doing so would result in static data that cannot be reloaded.
+ 1. Give the `vm.Graph` component `id="graph"` so that the `vm.Parameter` can target it. Dynamic data is referenced by the name of the data source `"iris"`.
+ 1. Create a `vm.Parameter` to target the `number_of_points` argument for the `data_frame` used in `graph`.
=== "Result"
- [![ParametrizedDynamicData]][ParametrizedDynamicData]
-
- [ParametrizedDynamicData]: ../../assets/user_guides/data/parametrized_dynamic_data.gif
+ [![ParametrizedDynamicData]][parametrizeddynamicdata]
Parametrized data loading is compatible with [caching](#configure-cache). The cache uses [memoization](https://flask-caching.readthedocs.io/en/latest/#memoization), so that the dynamic data function's arguments are included in the cache key. This means that `load_iris_data(number_of_points=10)` is cached independently of `load_iris_data(number_of_points=20)`.
!!! warning
-
You should always [treat the content of user input as untrusted](https://community.plotly.com/t/writing-secure-dash-apps-community-thread/54619). For example, you should not expose a filepath to load without passing it through a function like [`werkzeug.utils.secure_filename`](https://werkzeug.palletsprojects.com/en/3.0.x/utils/#werkzeug.utils.secure_filename), or you might enable arbitrary access to files on your server.
You cannot pass [nested parameters](parameters.md#nested-parameters) to dynamic data. You can only target the top-level arguments of the data loading function, not the nested keys in a dictionary.
@@ -354,7 +349,6 @@ When the page is refreshed, the behavior of a dynamic filter is as follows:
For example, let us add two filters to the [dynamic data example](#dynamic-data) above:
!!! example "Dynamic filters"
-
```py hl_lines="10 20 21"
from vizro import Vizro
import pandas as pd
@@ -386,8 +380,8 @@ For example, let us add two filters to the [dynamic data example](#dynamic-data)
```
1. We sample only 5 rather than 50 points so that changes to the available values in the filtered columns are more apparent when the page is refreshed.
- 2. This filter implicitly controls the dynamic data source `"iris"`, which supplies the `data_frame` to the targeted `vm.Graph`. On page refresh, Vizro reloads this data, finds all the unique values in the `"species"` column and sets the categorical selector's `options` accordingly.
- 3. Similarly, on page refresh, Vizro finds the minimum and maximum values of the `"sepal_length"` column in the reloaded data and sets new `min` and `max` values for the numerical selector accordingly.
+ 1. This filter implicitly controls the dynamic data source `"iris"`, which supplies the `data_frame` to the targeted `vm.Graph`. On page refresh, Vizro reloads this data, finds all the unique values in the `"species"` column and sets the categorical selector's `options` accordingly.
+ 1. Similarly, on page refresh, Vizro finds the minimum and maximum values of the `"sepal_length"` column in the reloaded data and sets new `min` and `max` values for the numerical selector accordingly.
Consider a filter that depends on dynamic data, where you do **not** want the available values to change when the dynamic data changes. You should manually specify the `selector`'s `options` field (categorical selector) or `min` and `max` fields (numerical selector). In the above example, this could be achieved as follows:
@@ -409,10 +403,13 @@ controls = [
When Vizro initially builds a filter that depends on parametrized dynamic data loading, data is loaded using the default argument values. This data is used to:
-* perform initial validation
-* check which data sources contain the specified `column` (unless `targets` is explicitly specified) and
-* find the type of selector to use (unless `selector` is explicitly specified).
+- perform initial validation
+- check which data sources contain the specified `column` (unless `targets` is explicitly specified) and
+- find the type of selector to use (unless `selector` is explicitly specified).
!!! note
-
When the value of a dynamic data parameter is changed by a dashboard user, the data underlying a dynamic filter can change. Currently this change affects page components such as `vm.Graph` but does not affect the available values shown in a dynamic filter, which only update on page refresh. This functionality will be coming soon!
+
+[databasic]: ../../assets/user_guides/data/data_pandas_dataframe.png
+[dynamicdata]: ../../assets/user_guides/data/dynamic_data.gif
+[parametrizeddynamicdata]: ../../assets/user_guides/data/parametrized_dynamic_data.gif
diff --git a/vizro-core/docs/pages/user-guides/extensions.md b/vizro-core/docs/pages/user-guides/extensions.md
index 2c7efc9ac..74a740448 100644
--- a/vizro-core/docs/pages/user-guides/extensions.md
+++ b/vizro-core/docs/pages/user-guides/extensions.md
@@ -2,64 +2,49 @@
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).
+- **[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.
+- **[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.
-* **[CSS customizations](#css-customizations)**. You can add custom CSS to any Vizro dashboard, enabling users to deviate from the default styling and create a unique look and feel for their dashboard.
-
-* **[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
+- **[CSS customizations](#css-customizations)**. You can add custom CSS to any Vizro dashboard, enabling users to deviate from the default styling and create a unique look and feel for their dashboard.
+- **[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
-
+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)).
+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.
-
+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).
+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
+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:
+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
@@ -93,14 +78,12 @@ enabling an interaction between data points in a scatter plot and the content of
## CSS customizations
-Vizro is opinionated about visual formatting, and some elements, such as the layout of the navigation and controls,
-are fixed. You can customize some settings such as background colors, fonts, and other styles via CSS overrides.
+Vizro is opinionated about visual formatting, and some elements, such as the layout of the navigation and controls, are fixed. You can customize some settings such as background colors, fonts, and other styles via CSS overrides.
For more information, see our documentation on [customizing CSS](custom-css.md)
## 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
+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)
diff --git a/vizro-core/docs/pages/user-guides/figure.md b/vizro-core/docs/pages/user-guides/figure.md
index 0589fad3b..03bfa412a 100644
--- a/vizro-core/docs/pages/user-guides/figure.md
+++ b/vizro-core/docs/pages/user-guides/figure.md
@@ -1,26 +1,19 @@
# How to use figures
-This guide shows you how to add any [Dash component](https://dash.plotly.com/#open-source-component-libraries) that needs to be reactive to [filter](filters.md) and [parameter](parameters.md) controls.
-If you want to add a static Dash component to your page, use [custom components](custom-components.md) instead.
+This guide shows you how to add any [Dash component](https://dash.plotly.com/#open-source-component-libraries) that needs to be reactive to [filter](filters.md) and [parameter](parameters.md) controls. If you want to add a static Dash component to your page, use [custom components](custom-components.md) instead.
-[`Figure`][vizro.models.Figure] provides a flexible foundation for all types of reactive Dash components in Vizro.
-The [`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] and [`AgGrid`][vizro.models.AgGrid] components are
-specific implementations of `Figure`. They serve as intuitive shortcuts, embedding behaviors and interactions specific
-to their purposes.
+[`Figure`][vizro.models.Figure] provides a flexible foundation for all types of reactive Dash components in Vizro. The [`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] and [`AgGrid`][vizro.models.AgGrid] components are specific implementations of `Figure`. They serve as intuitive shortcuts, embedding behaviors and interactions specific to their purposes.
-If these more specific models already achieve what you need then they should be used in preference to
-the more generic `Figure`. Remember that it is possible to supply [custom charts](custom-charts.md) to `Graph`
-and [custom tables](custom-tables.md) to `Table`.
+If these more specific models already achieve what you need then they should be used in preference to the more generic `Figure`. Remember that it is possible to supply [custom charts](custom-charts.md) to `Graph` and [custom tables](custom-tables.md) to `Table`.
-There are already a few figure functions you can reuse, see the section on [KPI cards](#key-performance-indicator-kpi-cards)
-for more details:
+There are already a few figure functions you can reuse, see the section on [KPI cards](#key-performance-indicator-kpi-cards) for more details:
- [`kpi_card`][vizro.figures.kpi_card]
- [`kpi_card_reference`][vizro.figures.kpi_card_reference]
The following flowchart shows what you need to consider when choosing which model to use:
-``` mermaid
+```mermaid
graph TD
first["`Does your desired component exist in Vizro, e.g. Graph, Table or AgGrid?`"]
specific-component([Use the specific component])
@@ -40,14 +33,12 @@ graph TD
classDef clickable color:#4051b5;
```
-
To add a `Figure` to your page:
1. Add the `Figure` model to the components argument of the [Page][vizro.models.Page] model.
-2. Use an existing figure function from [`vizro.figures`](../API-reference/figure-callables.md) and pass it to the `figure` argument of the `Figure` model.
+1. Use an existing figure function from [`vizro.figures`](../API-reference/figure-callables.md) and pass it to the `figure` argument of the `Figure` model.
!!! example "Use existing figure functions"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -99,40 +90,25 @@ To add a `Figure` to your page:
selector:
type: radio_items
layout:
- grid:
- [
- [0, -1, -1, -1],
- [-1, -1, -1, -1],
- [-1, -1, -1, -1],
- [-1, -1, -1, -1],
- [-1, -1, -1, -1],
- ]
+ grid: [[0, -1, -1, -1], [-1, -1, -1, -1], [-1, -1, -1, -1], [-1, -1, -1, -1],
+ [-1, -1, -1, -1]]
title: KPI card
```
- === "Result"
- [![Figure]][Figure]
-
- [Figure]: ../../assets/user_guides/figure/figure.png
+ === "Result"
+ [![Figure]][figure]
### Key Performance Indicator (KPI) cards
-A KPI card is a dynamic card that can display a single value, but optionally, can also include a title, icon, and reference value.
-It is a common visual component to display key metrics in a dashboard. Vizro supports two pre-defined KPI card functions:
-- [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card): A KPI card that shows a single value found
-by performing an aggregation function (by default, `sum`) over a specified column.
-Required arguments are `data_frame` and `value_column`.
+A KPI card is a dynamic card that can display a single value, but optionally, can also include a title, icon, and reference value. It is a common visual component to display key metrics in a dashboard. Vizro supports two pre-defined KPI card functions:
-- [`kpi_card_with_reference`](../API-reference/figure-callables.md#vizro.figures.kpi_card_reference): A KPI card that shows a single value
-and a delta comparison to a reference value found by performing an aggregation function (by default, `sum`) over the specified columns.
-Required arguments are `data_frame`, `value_column` and `reference_column`.
+- [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card): A KPI card that shows a single value found by performing an aggregation function (by default, `sum`) over a specified column. Required arguments are `data_frame` and `value_column`.
-As described in the [API reference](../API-reference/figure-callables.md) and illustrated in the below example, these
-functions have several arguments to customize your KPI cards. If you require a level of customization that is not
-possible with the built-in functions then you can create a [custom figure](custom-figures.md).
+- [`kpi_card_with_reference`](../API-reference/figure-callables.md#vizro.figures.kpi_card_reference): A KPI card that shows a single value and a delta comparison to a reference value found by performing an aggregation function (by default, `sum`) over the specified columns. Required arguments are `data_frame`, `value_column` and `reference_column`.
-!!! example "KPI card variations"
+As described in the [API reference](../API-reference/figure-callables.md) and illustrated in the below example, these functions have several arguments to customize your KPI cards. If you require a level of customization that cannot be done with the built-in functions then you can create a [custom figure](custom-figures.md).
+!!! example "KPI card variations"
=== "app.py"
```{.python pycafe-link}
import pandas as pd
@@ -258,8 +234,8 @@ possible with the built-in functions then you can create a [custom figure](custo
value_column: Actual
reference_column: Reference
title: KPI reference with formatting
- value_format: "{value:.2f}€"
- reference_format: "{delta:+.2f}€ vs. last year ({reference:.2f}€)"
+ value_format: '{value:.2f}€'
+ reference_format: '{delta:+.2f}€ vs. last year ({reference:.2f}€)'
type: figure
- figure:
_target_: kpi_card_reference
@@ -276,7 +252,9 @@ possible with the built-in functions then you can create a [custom figure](custo
grid: [[0, 1, 2, 3], [4, 5, 6, 7], [-1, -1, -1, -1], [-1, -1, -1, -1]]
title: KPI cards
```
+
=== "Result"
- [![KPICards]][KPICards]
+ [![KPICards]][kpicards]
- [KPICards]: ../../assets/user_guides/figure/kpi_cards.png
+[figure]: ../../assets/user_guides/figure/figure.png
+[kpicards]: ../../assets/user_guides/figure/kpi_cards.png
diff --git a/vizro-core/docs/pages/user-guides/filters.md b/vizro-core/docs/pages/user-guides/filters.md
index bc3649178..8228ecbe7 100644
--- a/vizro-core/docs/pages/user-guides/filters.md
+++ b/vizro-core/docs/pages/user-guides/filters.md
@@ -2,8 +2,7 @@
This guide shows you how to add filters to your dashboard. One main way to interact with the charts/components on your page is by filtering the underlying data. A filter selects a subset of rows of a component's underlying DataFrame which alters the appearance of that component on the page.
-The [`Page`][vizro.models.Page] model accepts the `controls` argument, where you can enter a [`Filter`][vizro.models.Filter] model.
-This model enables the automatic creation of [selectors](selectors.md) (for example, `Dropdown` or `RangeSlider`) that operate on the charts/components on the screen.
+The [`Page`][vizro.models.Page] model accepts the `controls` argument, where you can enter a [`Filter`][vizro.models.Filter] model. This model enables the automatic creation of [selectors](selectors.md) (for example, `Dropdown` or `RangeSlider`) that operate on the charts/components on the screen.
By default, filters that control components with [dynamic data](data.md#dynamic-data) are [dynamically updated](data.md#filters) when the underlying data changes while the dashboard is running.
@@ -12,7 +11,7 @@ By default, filters that control components with [dynamic data](data.md#dynamic-
To add a filter to your page, do the following:
1. add the [`Filter`][vizro.models.Filter] model into the `controls` argument of the [`Page`][vizro.models.Page] model
-2. configure the `column` argument, which denotes the target column to be filtered
+1. configure the `column` argument, which denotes the target column to be filtered
You can also set `targets` to specify which components on the page the filter should apply to. If this is not explicitly set then `targets` defaults to all components on the page whose data source includes `column`.
@@ -39,6 +38,7 @@ You can also set `targets` to specify which components on the page the filter sh
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -57,17 +57,15 @@ You can also set `targets` to specify which components on the page the filter sh
type: filter
title: My first page
```
- === "Result"
- [![Filter]][Filter]
-
- [Filter]: ../../assets/user_guides/control/control1.png
+ === "Result"
+ [![Filter]][filter]
The selector is configured automatically based on the target column type data as follows:
- - Categorical data uses [`vm.Dropdown(multi=True)`][vizro.models.Dropdown] where `options` is the set of unique values found in `column` across all the data sources of components in `targets`.
- - [Numerical data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_numeric_dtype.html) uses [`vm.RangeSlider`][vizro.models.RangeSlider] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`.
- - [Temporal data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_datetime64_any_dtype.html) uses [`vm.DatePicker(range=True)`][vizro.models.DatePicker] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`. A column can be converted to this type with [pandas.to_datetime](https://pandas.pydata.org/docs/reference/api/pandas.to_datetime.html).
+- Categorical data uses [`vm.Dropdown(multi=True)`][vizro.models.Dropdown] where `options` is the set of unique values found in `column` across all the data sources of components in `targets`.
+- [Numerical data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_numeric_dtype.html) uses [`vm.RangeSlider`][vizro.models.RangeSlider] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`.
+- [Temporal data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_datetime64_any_dtype.html) uses [`vm.DatePicker(range=True)`][vizro.models.DatePicker] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`. A column can be converted to this type with [pandas.to_datetime](https://pandas.pydata.org/docs/reference/api/pandas.to_datetime.html).
The following example demonstrates these default selector types.
@@ -107,6 +105,7 @@ The following example demonstrates these default selector types.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -129,15 +128,13 @@ The following example demonstrates these default selector types.
type: filter
title: My first page
```
- === "Result"
- [![Filter]][Filter]
- [Filter]: ../../assets/user_guides/selectors/default_filter_selectors.png
+ === "Result"
+ [![Filter]][filter]
## Change selector
-If you want to have a different selector for your filter, you can give the `selector` argument of the [`Filter`][vizro.models.Filter] a different selector model.
-Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropdown`][vizro.models.Dropdown], [`RadioItems`][vizro.models.RadioItems], [`RangeSlider`][vizro.models.RangeSlider], [`Slider`][vizro.models.Slider], and [`DatePicker`][vizro.models.DatePicker].
+If you want to have a different selector for your filter, you can give the `selector` argument of the [`Filter`][vizro.models.Filter] a different selector model. Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropdown`][vizro.models.Dropdown], [`RadioItems`][vizro.models.RadioItems], [`RangeSlider`][vizro.models.RangeSlider], [`Slider`][vizro.models.Slider], and [`DatePicker`][vizro.models.DatePicker].
!!! example "Filter with different selector"
=== "app.py"
@@ -162,6 +159,7 @@ Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropd
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -181,11 +179,9 @@ Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropd
type: filter
title: My first page
```
- === "Result"
-
- [![Selector]][Selector]
- [Selector]: ../../assets/user_guides/control/control2.png
+ === "Result"
+ [![Selector]][selector]
## Further customization
@@ -220,6 +216,7 @@ Below is an advanced example where we only target one page component, and where
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -244,17 +241,19 @@ Below is an advanced example where we only target one page component, and where
controls:
- column: petal_length
targets:
- - scatter_chart
+ - scatter_chart
selector:
step: 1
type: range_slider
type: filter
title: My first page
```
- === "Result"
-
- [![Advanced]][Advanced]
- [Advanced]: ../../assets/user_guides/control/control3.png
+ === "Result"
+ [![Advanced]][advanced]
To further customize selectors, see our [how-to-guide on creating custom components](custom-components.md).
+
+[advanced]: ../../assets/user_guides/control/control3.png
+[filter]: ../../assets/user_guides/control/control1.png
+[selector]: ../../assets/user_guides/control/control2.png
diff --git a/vizro-core/docs/pages/user-guides/graph.md b/vizro-core/docs/pages/user-guides/graph.md
index 36c670997..1c3ffc8bc 100755
--- a/vizro-core/docs/pages/user-guides/graph.md
+++ b/vizro-core/docs/pages/user-guides/graph.md
@@ -6,25 +6,18 @@ The [`Graph`][vizro.models.Graph] model is the most used component in many dashb
To add a [`Graph`][vizro.models.Graph] to your page, do the following:
-1. insert the [`Graph`][vizro.models.Graph] model into the `components` argument of the
-[`Page`][vizro.models.Page] model
-2. enter any of the currently available charts of the open source library [`plotly.express`](https://plotly.com/python/plotly-express/) into the `figure` argument
+1. insert the [`Graph`][vizro.models.Graph] model into the `components` argument of the [`Page`][vizro.models.Page] model
+1. enter any of the currently available charts of the open source library [`plotly.express`](https://plotly.com/python/plotly-express/) into the `figure` argument
!!! note
+ To use the [`plotly.express`](https://plotly.com/python/plotly-express/) chart in a Vizro dashboard, you need to import it as `import vizro.plotly.express as px`. This leaves any of the [`plotly.express`](https://plotly.com/python/plotly-express/) functionality untouched yet enables _direct insertion_ into the [`Graph`][vizro.models.Graph] model _as is_.
- In order to use the [`plotly.express`](https://plotly.com/python/plotly-express/) chart in a Vizro dashboard, you need to import it as `import vizro.plotly.express as px`.
- This leaves any of the [`plotly.express`](https://plotly.com/python/plotly-express/) functionality untouched, but allows _direct insertion_ into the [`Graph`][vizro.models.Graph] model _as is_.
-
- Note also that the `plotly.express` chart needs to have a `data_frame` argument. In case you require a chart without
- a `data_frame` argument (for example, the [`imshow` chart](https://plotly.com/python/imshow/)), refer to our
- [guide on custom charts](custom-charts.md).
-
+ Note also that the `plotly.express` chart needs to have a `data_frame` argument. In case you require a chart without a `data_frame` argument (for example, the [`imshow` chart](https://plotly.com/python/imshow/)), refer to our [guide on custom charts](custom-charts.md).
## Insert Plotly chart
!!! example "Graph"
=== "app.py"
-
```{.python pycafe-link}
import vizro.models as vm
import vizro.plotly.express as px
@@ -47,25 +40,24 @@ To add a [`Graph`][vizro.models.Graph] to your page, do the following:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: scatter_matrix
- color: species
- data_frame: iris
- dimensions: ["sepal_length", "sepal_width", "petal_length", "petal_width"]
- type: graph
- title: My first page
+ - components:
+ - figure:
+ _target_: scatter_matrix
+ color: species
+ data_frame: iris
+ dimensions: [sepal_length, sepal_width, petal_length, petal_width]
+ type: graph
+ title: My first page
```
- === "Result"
- [![Graph]][Graph]
-
- [Graph]: ../../assets/user_guides/components/graph.png
+ === "Result"
+ [![Graph]][graph]
In the Python example we directly inserted the pandas DataFrame `df` into `figure=px.scatter_matrix(df, ...)`. This is [one way to supply data to a chart](data.md#supply-directly). For the YAML version, we [refer to the data source by name](data.md#reference-by-name) as `data_frame: iris`. For a full explanation of the different methods you can use to send data to your dashboard, see [our guide to using data in Vizro](data.md).
@@ -73,31 +65,24 @@ In the Python example we directly inserted the pandas DataFrame `df` into `figur
You will need to create a custom chart if you want to customize the Plotly chart beyond a function call, for example by:
-* using post-update methods like `update_layout`, `update_xaxes`, `update_traces`, or
-* by creating a custom `plotly.graph_objects.Figure()` object and manually adding traces with `add_trace`.
-
-For more details, refer to our [user guide on custom chart](custom-charts.md) and the
-[Plotly documentation on updating figures](https://plotly.com/python/creating-and-updating-figures/).
+- using post-update methods like `update_layout`, `update_xaxes`, `update_traces`, or
+- by creating a custom `plotly.graph_objects.Figure()` object and manually adding traces with `add_trace`.
+For more details, refer to our [user guide on custom chart](custom-charts.md) and the [Plotly documentation on updating figures](https://plotly.com/python/creating-and-updating-figures/).
## Add title, header, and footer
-The [`Graph`][vizro.models.Graph] accepts a `title`, `header` and `footer` argument. This is useful for providing
-context to the data being displayed, or for adding a description of the data.
+The [`Graph`][vizro.models.Graph] accepts a `title`, `header` and `footer` argument. This is useful for context on the data being displayed, or for adding a description of the data.
- **title**: Displayed as an [H3 header](https://dash.plotly.com/dash-html-components/h3), useful for summarizing the main topic or insight of the component.
- **header**: Accepts markdown text, ideal for extra descriptions, subtitles, or detailed data insights.
- **footer**: Accepts markdown text, commonly used for citing data sources, providing information on the last update, or adding disclaimers.
-
!!! note
-
- Although you can directly provide a `title` to the Plotly Express chart, we recommend using `Graph.title` for
- proper alignment with other components on the screen.
+ Although you can directly give a `title` to the Plotly Express chart, we recommend using `Graph.title` for proper alignment with other components on the screen.
!!! example "Formatted Graph"
=== "app.py"
-
```{.python pycafe-link}
import vizro.models as vm
@@ -126,31 +111,34 @@ context to the data being displayed, or for adding a description of the data.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: scatter
- x: sepal_width
- y: sepal_length
- color: species
- data_frame: iris
- title: Relationships between Sepal Width and Sepal Length
- header: |
- Each point in the scatter plot represents one of the 150 iris flowers, with colors indicating their
- types. The Setosa type is easily identifiable by its short and wide sepals.
-
- However, there is still overlap between the Versicolor and Virginica types when considering only sepal
- width and length.
- footer: |
- SOURCE: **Plotly iris data set, 2024**
- type: graph
- title: Formatted Graph
+ - components:
+ - figure:
+ _target_: scatter
+ x: sepal_width
+ y: sepal_length
+ color: species
+ data_frame: iris
+ title: Relationships between Sepal Width and Sepal Length
+ header: |
+ Each point in the scatter plot represents one of the 150 iris flowers, with colors indicating their
+ types. The Setosa type is easily identifiable by its short and wide sepals.
+
+ However, there is still overlap between the Versicolor and Virginica types when considering only sepal
+ width and length.
+ footer: |
+ SOURCE: **Plotly iris data set, 2024**
+ type: graph
+ title: Formatted Graph
```
+
=== "Result"
- [![FormattedGraph]][FormattedGraph]
+ [![FormattedGraph]][formattedgraph]
- [FormattedGraph]: ../../assets/user_guides/components/formatted_graph.png
+[formattedgraph]: ../../assets/user_guides/components/formatted_graph.png
+[graph]: ../../assets/user_guides/components/graph.png
diff --git a/vizro-core/docs/pages/user-guides/install.md b/vizro-core/docs/pages/user-guides/install.md
index 4d4c01239..6a07911e5 100644
--- a/vizro-core/docs/pages/user-guides/install.md
+++ b/vizro-core/docs/pages/user-guides/install.md
@@ -8,8 +8,8 @@ We recommend that you create a virtual environment for each Vizro project you wo
## Prerequisites to working locally
-* **Python**: Vizro supports macOS, Linux, and Windows. It works with Python 3.9 and later.
-* **Virtual environment**: You specify the version of Python to use with Vizro when you set up the virtual environment. See the following references to learn more about [Python virtual environments](https://realpython.com/python-virtual-environments-a-primer/), [Conda virtual environments](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#starting-conda) or [watch an explainer video about them](https://youtu.be/YKfAwIItO7M).
+- **Python**: Vizro supports macOS, Linux, and Windows. It works with Python 3.9 and later.
+- **Virtual environment**: You specify the version of Python to use with Vizro when you set up the virtual environment. See the following references to learn more about [Python virtual environments](https://realpython.com/python-virtual-environments-a-primer/), [Conda virtual environments](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#starting-conda) or [watch an explainer video about them](https://youtu.be/YKfAwIItO7M).
### How to create a virtual environment for your Vizro project
diff --git a/vizro-core/docs/pages/user-guides/kedro-data-catalog.md b/vizro-core/docs/pages/user-guides/kedro-data-catalog.md
index 0e2b0954e..ce4b060fa 100644
--- a/vizro-core/docs/pages/user-guides/kedro-data-catalog.md
+++ b/vizro-core/docs/pages/user-guides/kedro-data-catalog.md
@@ -3,6 +3,7 @@
This page describes how to integrate Vizro with [Kedro](https://docs.kedro.org/en/stable/index.html), an open-source Python framework to create reproducible, maintainable, and modular data science code. For Pandas datasets registered in a Kedro data catalog, Vizro provides a convenient way to visualize them.
## Installation
+
If you already have Kedro installed then you do not need to install any extra dependencies. If you do not have Kedro installed then you should run:
```bash
@@ -10,7 +11,9 @@ pip install vizro[kedro]
```
## Use datasets from the Kedro Data Catalog
+
`vizro.integrations.kedro` provides functions to help generate and process a [Kedro Data Catalog](https://docs.kedro.org/en/stable/data/index.html). Given a Kedro Data Catalog `catalog`, the general pattern to add datasets into the Vizro data manager is:
+
```python
from vizro.integrations import kedro as kedro_integration
from vizro.managers import data_manager
@@ -25,15 +28,14 @@ This imports all datasets of type [`kedro_datasets.pandas`](https://docs.kedro.o
The `catalog` variable may have been created in a number of different ways:
1. Kedro project path. Vizro exposes a helper function `vizro.integrations.kedro.catalog_from_project` to generate a `catalog` given the path to a Kedro project.
-2. [Kedro Jupyter session](https://docs.kedro.org/en/stable/notebooks_and_ipython/kedro_and_notebooks.html). This automatically exposes `catalog`.
-3. Data Catalog configuration file (`catalog.yaml`). This can create a `catalog` entirely independently of a Kedro project using [`kedro.io.DataCatalog.from_config`](https://docs.kedro.org/en/stable/kedro.io.DataCatalog.html#kedro.io.DataCatalog.from_config).
+1. [Kedro Jupyter session](https://docs.kedro.org/en/stable/notebooks_and_ipython/kedro_and_notebooks.html). This automatically exposes `catalog`.
+1. Data Catalog configuration file (`catalog.yaml`). This can create a `catalog` entirely independently of a Kedro project using [`kedro.io.DataCatalog.from_config`](https://docs.kedro.org/en/stable/kedro.io.DataCatalog.html#kedro.io.DataCatalog.from_config).
The full code for these different cases is given below.
!!! example "Import a Kedro Data Catalog into the Vizro data manager"
-
=== "app.py (Kedro project path)"
- ```py
+ ```python
from vizro.integrations import kedro as kedro_integration
from vizro.managers import data_manager
@@ -43,16 +45,18 @@ The full code for these different cases is given below.
for dataset_name, dataset in kedro_integration.datasets_from_catalog(catalog).items():
data_manager[dataset_name] = dataset
```
+
=== "app.ipynb (Kedro Jupyter session)"
- ```py
+ ```python
from vizro.managers import data_manager
for dataset_name, dataset in kedro_integration.datasets_from_catalog(catalog).items():
data_manager[dataset_name] = dataset
```
+
=== "app.py (Data Catalog configuration file)"
- ```py
+ ```python
from kedro.io import DataCatalog
import yaml
diff --git a/vizro-core/docs/pages/user-guides/layouts.md b/vizro-core/docs/pages/user-guides/layouts.md
index 8361560db..af66ec301 100644
--- a/vizro-core/docs/pages/user-guides/layouts.md
+++ b/vizro-core/docs/pages/user-guides/layouts.md
@@ -3,11 +3,10 @@
The [`Page`][vizro.models.Page] model accepts a `layout` argument that enables custom arrangement of charts and components on the screen. This guide shows how to customize the grid specifications in the [`Layout`][vizro.models.Layout].
## The default layout
-The `layout` argument of the [`Page`][vizro.models.Page] model is optional. If no layout is specified, all charts/components are automatically [**stacked vertically**](layouts.md#vertical-and-horizontal-stacking) on the page in one column.
-If you are happy with that arrangement, you can create your charts/components without providing a [`Layout`][vizro.models.Layout].
-!!! example "Default Layout"
+The `layout` argument of the [`Page`][vizro.models.Page] model is optional. If no layout is specified, all charts/components are automatically [**stacked vertically**](layouts.md#vertical-and-horizontal-stacking) on the page in one column. If you are happy with that arrangement, you can create your charts/components without providing a [`Layout`][vizro.models.Layout].
+!!! example "Default Layout"
=== "app.py"
```{.python pycafe-link}
from vizro import Vizro
@@ -23,35 +22,33 @@ If you are happy with that arrangement, you can create your charts/components wi
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- title: two_left
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ title: two_left
```
- === "Result"
- [![Layout]][Layout]
-
- [Layout]: ../../assets/user_guides/layout/two_left.png
-
+ === "Result"
+ [![Layout]][layout]
## Configure the grid
+
To customize the grid arrangement, configure the `grid` parameter of the [`Layout`][vizro.models.Layout] model.
The example below shows an example of a valid `grid`:
```python title="Basic example"
-grid = [[0, 1],
- [0, 2]]
+grid = [[0, 1], [0, 2]]
```
- The `grid` must be provided as `list[list[int]]` (for example, `grid = [[0, 1], [0, 2]]`).
@@ -64,16 +61,12 @@ grid = [[0, 1],
- The area spanned by a chart/component in the grid must be rectangular.
- The grid can be arbitrarily large, allowing arbitrarily granular control of the grid.
-
## Vertical and horizontal stacking
+
As described above, when no `Layout` is specified, components are presented **vertically** as a single-column stack. If you have three components, the default `Layout.grid` will be as follows, with three equally sized rows, each containing a component spanning the entire width:
```python title="Vertical stacking"
-grid = [
- [0],
- [1],
- [2]
- ]
+grid = [[0], [1], [2]]
```
To present components **horizontally** in one row:
@@ -89,8 +82,8 @@ This defines a single row that occupies the entire width and height, divided int
## Grid - basic example
-!!! example "Grid Arrangement - Basic Example"
+!!! example "Grid Arrangement - Basic Example"
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -109,39 +102,37 @@ This defines a single row that occupies the entire width and height, divided int
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- - text: |
- # Component 2
- type: card
- layout:
- grid: [[0, 1], [0, 2]]
- title: one_left_two_right
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ layout:
+ grid: [[0, 1], [0, 2]]
+ title: one_left_two_right
```
- === "Result"
- [![Grid]][Grid]
- [Grid]: ../../assets/user_guides/layout/one_left_two_right.png
+ === "Result"
+ [![Grid]][grid]
## Grid - advanced example
If you want to divide the grid into subgrids with finer control over these, you can use [`Containers`](container.md). See our section on [when to use `Containers` vs. `Page.layout`](container.md#when-to-use-containers) for more information.
-The `Layout` provides full control over the arrangement of top-level components within a page,
-allowing arbitrarily granular control of the grid by creating larger grids.
+The `Layout` provides full control over the arrangement of top-level components within a page, allowing arbitrarily granular control of the grid by creating larger grids.
!!! example "Grid Arrangement - Advanced Example"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -208,6 +199,7 @@ allowing arbitrarily granular control of the grid by creating larger grids.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -260,44 +252,44 @@ allowing arbitrarily granular control of the grid by creating larger grids.
grid: [[0, 1, 3, 4], [2, 2, 3, 4]]
title: Custom Layout - Advanced Example
```
- === "Result"
- [![GridAdv]][GridAdv]
- [GridAdv]: ../../assets/user_guides/layout/grid_advanced.png
+ === "Result"
+ [![GridAdv]][gridadv]
## Custom layout examples
+
Here is a reference table of example layouts:
+
one row with one component, second row with two components stacked horizontally
-| Layout needed | Grid | Code |
-|--------------------------------|----------------------------|-------------------------------------------------------------------------------------|
-| | | `layout=vm.Layout(grid=[[0]])` |
-| | | `layout=vm.Layout(grid=[[0],[1]])` |
-| | | `layout=vm.Layout(grid=[[0,1]])` |
-| | | `layout=vm.Layout(grid=[[0],[1],[2]])` or
`layout=None` |
-| | | `layout=vm.Layout(grid=[[0,1],[0,2]])` |
-| | | `layout=vm.Layout(grid=[[0,0],[1,2]])` |
-| | | `layout=vm.Layout(grid=[[0,1],[2,2]])` |
-| | | `layout=vm.Layout(grid=[[0,1],[0,2],[0,3]])` |
-| | | `layout=vm.Layout(grid=[[0,1],[2,3]])` |
-| | | `layout=vm.Layout(grid=[[0,3],[1,3],[2,3]])` |
-| | | `layout=vm.Layout(grid=[[0,0,0],[1,2,3]])` |
-| | | `layout=vm.Layout(grid=[[0,1,2],[3,3,3]])` |
+| Layout needed | Grid | Code |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| | | `layout=vm.Layout(grid=[[0]])` |
+| | | `layout=vm.Layout(grid=[[0],[1]])` |
+| | | `layout=vm.Layout(grid=[[0,1]])` |
+| | | `layout=vm.Layout(grid=[[0],[1],[2]])` or
`layout=None` |
+| | | `layout=vm.Layout(grid=[[0,1],[0,2]])` |
+| | | `layout=vm.Layout(grid=[[0,0],[1,2]])` |
+| | | `layout=vm.Layout(grid=[[0,1],[2,2]])` |
+| | | `layout=vm.Layout(grid=[[0,1],[0,2],[0,3]])` |
+| | | `layout=vm.Layout(grid=[[0,1],[2,3]])` |
+| | | `layout=vm.Layout(grid=[[0,3],[1,3],[2,3]])` |
+| | | `layout=vm.Layout(grid=[[0,0,0],[1,2,3]])` |
+| | | `layout=vm.Layout(grid=[[0,1,2],[3,3,3]])` |
## Add empty sections to the grid
+
One approach to organize the dashboard's layout involves integrating empty sections by specifying `-1` within the grid layout.
```python title="Example"
-grid = [[0, 1, -1],
- [0, 2, -1]]
+grid = [[0, 1, -1], [0, 2, -1]]
```
!!! example "Adding Empty Spaces"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -316,38 +308,38 @@ grid = [[0, 1, -1],
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- - text: |
- # Component 2
- type: card
- layout:
- grid: [[0, 1, -1], [0, 2, -1]]
- title: Adding empty spaces
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ layout:
+ grid: [[0, 1, -1], [0, 2, -1]]
+ title: Adding empty spaces
```
- === "Result"
- [![GridEmpty]][GridEmpty]
- [GridEmpty]: ../../assets/user_guides/layout/layout_empty_spaces.png
+ === "Result"
+ [![GridEmpty]][gridempty]
## Control the scroll behavior
+
By default, the grid fits all charts/components on the screen. This can lead to distortions such that the chart/component looks squashed. To control the scroll behavior, you can specify the following:
- `row_min_height`: Sets a chart/component's minimum height. Defaults to 0px.
- `col_min_width`: Sets a chart/component's minimum width. Defaults to 0px.
!!! example "Activate Scrolling"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -371,59 +363,63 @@ By default, the grid fits all charts/components on the screen. This can lead to
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- - text: |
- # Component 2
- type: card
- - text: |
- # Component 2
- type: card
- - text: |
- # Component 4
- type: card
- - text: |
- # Component 5
- type: card
- - text: |
- # Component 6
- type: card
- - text: |
- # Component 7
- type: card
- layout:
- grid: [[0], [1], [2], [3], [4], [5], [6], [7]]
- row_min_height: 240px
- title: Activate scrolling
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ - text: |
+ # Component 4
+ type: card
+ - text: |
+ # Component 5
+ type: card
+ - text: |
+ # Component 6
+ type: card
+ - text: |
+ # Component 7
+ type: card
+ layout:
+ grid: [[0], [1], [2], [3], [4], [5], [6], [7]]
+ row_min_height: 240px
+ title: Activate scrolling
```
- === "Result"
- [![GridScroll]][GridScroll]
-
- [GridScroll]: ../../assets/user_guides/layout/grid_scroll.png
+ === "Result"
+ [![GridScroll]][gridscroll]
## Further customization
-For further customization, such as changing the gap between row and column, refer to the
-documentation of the [`Layout`][vizro.models.Layout] model.
+
+For further customization, such as changing the gap between row and column, refer to the documentation of the [`Layout`][vizro.models.Layout] model.
## Alternative layout approaches
+
In general, any arbitrarily granular layout can already be achieved using [`Page.layout`](layouts.md) alone and is our recommended approach if you want to arrange components on a page with consistent row and/or column spacing.
!!! note "Alternative layout approaches: `Tabs` and `Containers`"
-
- [`Tabs`][vizro.models.Tabs] and [`Containers`][vizro.models.Container] provide an alternative approach to customize your page layout.
- For example, if you want to have more granular control and break the overall page grid into subgrids, see our [user guide on Containers](container.md).
+ [`Tabs`][vizro.models.Tabs] and [`Containers`][vizro.models.Container] offer an alternative approach to customize your page layout. For example, if you want to have more granular control and break the overall page grid into subgrids, see our [user guide on Containers](container.md).
If you want to display multiple containers on one page by putting them into the same screen space, and letting the user switch between them, see our [user guide on Tabs](tabs.md).
{ width="500" }
+
+[grid]: ../../assets/user_guides/layout/one_left_two_right.png
+[gridadv]: ../../assets/user_guides/layout/grid_advanced.png
+[gridempty]: ../../assets/user_guides/layout/layout_empty_spaces.png
+[gridscroll]: ../../assets/user_guides/layout/grid_scroll.png
+[layout]: ../../assets/user_guides/layout/two_left.png
diff --git a/vizro-core/docs/pages/user-guides/navigation.md b/vizro-core/docs/pages/user-guides/navigation.md
index 41c6bb9dc..75a661470 100644
--- a/vizro-core/docs/pages/user-guides/navigation.md
+++ b/vizro-core/docs/pages/user-guides/navigation.md
@@ -2,8 +2,7 @@
This guide shows you how to use and customize the navigation that appears on the left of your dashboard.
-The [`Dashboard`][vizro.models.Dashboard] model accepts a `navigation` argument, where you can enter a [`Navigation`][vizro.models.Navigation] model. This enables you to group pages together and customize how they appear in your navigation.
-The dashboard includes a collapsible side panel that users can minimize or expand by a button click. The collapse button, located in the top right corner of the side panel, is visible by default for user convenience.
+The [`Dashboard`][vizro.models.Dashboard] model accepts a `navigation` argument, where you can enter a [`Navigation`][vizro.models.Navigation] model. This enables you to group pages together and customize how they appear in your navigation. The dashboard includes a collapsible side panel that users can minimize or expand by a button click. The collapse button, located in the top right corner of the side panel, is visible by default for user convenience.
## Use the default navigation
@@ -56,8 +55,8 @@ By default, if the `navigation` argument is not specified, Vizro creates a navig
type: graph
title: My first page
- components:
- - text: My text here
- type: card
+ - text: My text here
+ type: card
title: My second page
- components:
- figure:
@@ -69,10 +68,9 @@ By default, if the `navigation` argument is not specified, Vizro creates a navig
type: graph
title: My third page
```
- === "Result"
- [![DefaultNavigation]][DefaultNavigation]
- [DefaultNavigation]: ../../assets/user_guides/navigation/default_navigation.png
+ === "Result"
+ [![DefaultNavigation]][defaultnavigation]
## Include a subset of pages
@@ -132,17 +130,15 @@ To include only some of your dashboard pages in your navigation then list them i
- My first page
- My second page
```
- === "Result"
- [![OnlySomePages]][OnlySomePages]
- [OnlySomePages]: ../../assets/user_guides/navigation/only_some_pages.png
+ === "Result"
+ [![OnlySomePages]][onlysomepages]
## Group pages
You can also group your pages together by specifying `pages` as a dictionary:
!!! example "Grouping pages"
-
=== "snippet.py"
```py
# page_1, page_2, page_3 defined as in default example
@@ -154,7 +150,6 @@ You can also group your pages together by specifying `pages` as a dictionary:
```
=== "app.py"
-
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -187,6 +182,7 @@ You can also group your pages together by specifying `pages` as a dictionary:
)
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -200,18 +196,15 @@ You can also group your pages together by specifying `pages` as a dictionary:
Group B:
- My third page
```
- === "Result"
- [![GroupedNavigation]][GroupedNavigation]
-
- [GroupedNavigation]: ../../assets/user_guides/navigation/grouped_navigation.png
+ === "Result"
+ [![GroupedNavigation]][groupednavigation]
## Use a navigation bar with icons
Another way to group together pages in the navigation is to use a [`NavBar`][vizro.models.NavBar] with icons. The simplest way to use this is to change the `nav_selector` specified in [`Navigation`][vizro.models.Navigation]:
!!! example "Using `NavBar`"
-
=== "snippet.py"
```py
# page_1, page_2, page_3 defined as in default example
@@ -223,8 +216,8 @@ Another way to group together pages in the navigation is to use a [`NavBar`][viz
)
Vizro().build(dashboard).run()
```
- === "app.py"
+ === "app.py"
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -276,14 +269,11 @@ Another way to group together pages in the navigation is to use a [`NavBar`][viz
nav_selector:
type: nav_bar
```
- === "Result"
- [![NavBar]][NavBar]
-
- [NavBar]: ../../assets/user_guides/navigation/nav_bar.png
+ === "Result"
+ [![NavBar]][navbar]
-Here, the first level of the navigation hierarchy ("Group A" and "Group B") is represented by an icon in a navigation bar, and the second level of the navigation (the pages) is represented by an accordion.
-By default, the set of icons used are the [`filter` icons from the Google Material icons library](https://fonts.google.com/icons?icon.query=filter). The icon label ("Group A" and "Group B") appears as a tooltip on hovering over the icon.
+Here, the first level of the navigation hierarchy ("Group A" and "Group B") is represented by an icon in a navigation bar, and the second level of the navigation (the pages) is represented by an accordion. By default, the set of icons used are the [`filter` icons from the Google Material icons library](https://fonts.google.com/icons?icon.query=filter). The icon label ("Group A" and "Group B") appears as a tooltip on hovering over the icon.
## Customize the navigation bar
@@ -314,7 +304,6 @@ The same configuration for [grouping pages](#group-pages) applies inside a `NavL
```
=== "app.py"
-
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -375,10 +364,9 @@ The same configuration for [grouping pages](#group-pages) applies inside a `NavL
Group B:
- My third page
```
- === "Result"
- [![AccordionInsideNavBar]][AccordionInsideNavBar]
- [AccordionInsideNavBar]: ../../assets/user_guides/navigation/accordion_inside_nav_bar.png
+ === "Result"
+ [![AccordionInsideNavBar]][accordioninsidenavbar]
You can alter the icons used by specifying the name of the icon in the [Google Material icons library](https://fonts.google.com/icons):
@@ -402,8 +390,8 @@ You can alter the icons used by specifying the name of the icon in the [Google M
),
)
```
- === "app.py"
+ === "app.py"
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -468,7 +456,13 @@ You can alter the icons used by specifying the name of the icon in the [Google M
pages:
- My third page
```
- === "Result"
- [![CustomIcons]][CustomIcons]
- [CustomIcons]: ../../assets/user_guides/navigation/custom_icons.png
+ === "Result"
+ [![CustomIcons]][customicons]
+
+[accordioninsidenavbar]: ../../assets/user_guides/navigation/accordion_inside_nav_bar.png
+[customicons]: ../../assets/user_guides/navigation/custom_icons.png
+[defaultnavigation]: ../../assets/user_guides/navigation/default_navigation.png
+[groupednavigation]: ../../assets/user_guides/navigation/grouped_navigation.png
+[navbar]: ../../assets/user_guides/navigation/nav_bar.png
+[onlysomepages]: ../../assets/user_guides/navigation/only_some_pages.png
diff --git a/vizro-core/docs/pages/user-guides/pages.md b/vizro-core/docs/pages/user-guides/pages.md
index 7ae944e9b..71e01e9f9 100644
--- a/vizro-core/docs/pages/user-guides/pages.md
+++ b/vizro-core/docs/pages/user-guides/pages.md
@@ -1,7 +1,6 @@
# How to use pages
-This guide shows you how to add pages to your dashboard and customize the URL paths if needed.
-A [`Page`][vizro.models.Page] lets you place and arrange your dashboard content (for example, chart/components, tables, and text)
-and configure your dashboard interactions (such as filters and parameters).
+
+This guide shows you how to add pages to your dashboard and customize the URL paths if needed. A [`Page`][vizro.models.Page] lets you place and arrange your dashboard content (for example, chart/components, tables, and text) and configure your dashboard interactions (such as filters and parameters).
The [`Dashboard`][vizro.models.Dashboard] model accepts the `pages` argument, where you can insert your [`Page`][vizro.models.Page].
@@ -10,19 +9,19 @@ The [`Dashboard`][vizro.models.Dashboard] model accepts the `pages` argument, wh
A [`Page`][vizro.models.Page] is split up into four main containers:
1. The **navigation container** where you can customize your `navigation` (see [Dashboard](dashboard.md) and [Navigation](navigation.md) for more information). Note that the navigation container needs to be configured via the Dashboard.
-2. The **control container** where you can add your `controls` (see [Filters](filters.md) or [Parameters](parameters.md)) to interact with the dashboard
-3. The **page header** that contains the page title and the theme toggle switch button
-4. The **component container** where you can add your [components](components.md) to visualize your data
+1. The **control container** where you can add your `controls` (see [Filters](filters.md) or [Parameters](parameters.md)) to interact with the dashboard
+1. The **page header** that contains the page title and the theme toggle switch button
+1. The **component container** where you can add your [components](components.md) to visualize your data
To create and add a page to your dashboard, do the following steps:
1. Set a `title` for your [`Page`][vizro.models.Page]
-2. Configure your `components`, see our guide on the [various options](components.md)
-3. (optional) Configure your `controls` , see our guides on [Filters](filters.md) and [Parameters](parameters.md)
-4. (optional) Configure your `layout` , see our guide on [Layouts](layouts.md)
-5. (optional) Give a `description` of your `Page` to the app's [meta tags](https://metatags.io/)
+1. Configure your `components`, see our guide on the [various options](components.md)
+1. (optional) Configure your `controls` , see our guides on [Filters](filters.md) and [Parameters](parameters.md)
+1. (optional) Configure your `layout` , see our guide on [Layouts](layouts.md)
+1. (optional) Give a `description` of your `Page` to the app's [meta tags](https://metatags.io/)
!!! example "Page"
=== "app.py"
@@ -51,51 +50,47 @@ To create and add a page to your dashboard, do the following steps:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: sunburst
- path: ['continent', 'country']
- values: pop
- color: lifeExp
- data_frame: gapminder
- id: sunburst
- type: graph
- controls:
- - column: continent
- targets:
- - sunburst
- type: filter
- - selector:
- options: ['lifeExp', 'pop']
- title: Color
- type: radio_items
- targets:
- - sunburst.color
- type: parameter
- title: Page Title
- description: "Longer description of the page content"
+ - components:
+ - figure:
+ _target_: sunburst
+ path: [continent, country]
+ values: pop
+ color: lifeExp
+ data_frame: gapminder
+ id: sunburst
+ type: graph
+ controls:
+ - column: continent
+ targets: [sunburst]
+ type: filter
+ - selector:
+ options: [lifeExp, pop]
+ title: Color
+ type: radio_items
+ targets: [sunburst.color]
+ type: parameter
+ title: Page Title
+ description: Longer description of the page content
```
- === "Result"
- [![Page]][Page]
- [Page]: ../../assets/user_guides/pages/page_sunburst.png
+ === "Result"
+ [![Page]][page]
An accordion page selector is automatically added to your dashboard in the top-left of the control container for through the different pages. It will not be added if your dashboard consists of only one page.
You can additionally navigate through the different pages by going directly to the relevant page URL (more details in next section).
-
## Customize the page URL
-By default, the page URL is automatically generated based on the `id` of the page. For example, if `id="This is my first page"`
-the generated page URL will be `path=this-is-my-first-page`. You can then access the page via `localhost:/this-is-my-first-page`.
-Note that the page `id` defaults to be the same as the page `title` if not set.
-If you have multiple pages with the same `title` then you must assign a unique `id`.
+By default, the page URL is automatically generated based on the `id` of the page. For example, if `id="This is my first page"` the generated page URL will be `path=this-is-my-first-page`. You can then access the page via `localhost:/this-is-my-first-page`.
+
+Note that the page `id` defaults to be the same as the page `title` if not set. If you have multiple pages with the same `title` then you must assign a unique `id`.
The first page always has the URL prefix `/` assigned. A custom URL can, therefore, not be created for the first page.
@@ -137,39 +132,40 @@ To customize the page URL, pass a valid URL name to the `path` argument of [`Pag
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- Commodi repudiandae consequuntur voluptatum.
- type: card
- title: Page 1
- - components:
- - figure:
- _target_: sunburst
- path: ['continent', 'country']
- values: pop
- color: lifeExp
- data_frame: gapminder
- id: sunburst
- type: graph
- controls:
- - column: continent
- targets:
- - sunburst
- type: filter
- - selector:
- options: ['lifeExp', 'pop']
- title: Color
- type: radio_items
- targets:
- - sunburst.color
- type: parameter
- title: Page 2
- path: my-custom-url
+ - components:
+ - text: |
+ Commodi repudiandae consequuntur voluptatum.
+ type: card
+ title: Page 1
+ - components:
+ - figure:
+ _target_: sunburst
+ path: [continent, country]
+ values: pop
+ color: lifeExp
+ data_frame: gapminder
+ id: sunburst
+ type: graph
+ controls:
+ - column: continent
+ targets: [sunburst]
+ type: filter
+ - selector:
+ options: [lifeExp, pop]
+ title: Color
+ type: radio_items
+ targets: [sunburst.color]
+ type: parameter
+ title: Page 2
+ path: my-custom-url
```
You can now access the first page via `localhost:/` and the second page via `localhost:/my-custom-url`.
+
+[page]: ../../assets/user_guides/pages/page_sunburst.png
diff --git a/vizro-core/docs/pages/user-guides/parameters.md b/vizro-core/docs/pages/user-guides/parameters.md
index bb39a7a0c..c82707d4a 100644
--- a/vizro-core/docs/pages/user-guides/parameters.md
+++ b/vizro-core/docs/pages/user-guides/parameters.md
@@ -9,8 +9,8 @@ The [`Page`][vizro.models.Page] model accepts the `controls` argument, where you
To add a parameter to your page, do the following:
1. add the [`Parameter`][vizro.models.Parameter] model into the `controls` argument of the [`Page`][vizro.models.Page] model.
-2. add the `targets` argument
-3. add a selector model to the `selector` argument.
+1. add the `targets` argument
+1. add a selector model to the `selector` argument.
In the `targets` argument, you can specify the component and function argument that the parameter should be applied to in the form of `.` (for example, `scatter_chart.title`).
@@ -48,6 +48,7 @@ Unlike for the [`Filter`][vizro.models.Filter] model, you also have to configure
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -64,18 +65,17 @@ Unlike for the [`Filter`][vizro.models.Filter] model, you also have to configure
type: graph
controls:
- selector:
- options: ["My scatter chart", "A better title!", "Another title..."]
- multi: False
+ options: [My scatter chart, A better title!, Another title...]
+ multi: false
type: dropdown
targets:
- scatter_chart.title
type: parameter
title: My first page
```
- === "Result"
- [![Parameter]][Parameter]
- [Parameter]: ../../assets/user_guides/control/control4.png
+ === "Result"
+ [![Parameter]][parameter]
If you would like to pass `None` as a parameter and make a parameter optional, you can specify the string `"NONE"` in the `options` or `value` field.
@@ -133,6 +133,7 @@ If you want to change nested parameters, you can specify the `targets` argument
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -146,7 +147,7 @@ If you want to change nested parameters, you can specify the `targets` argument
y: sepal_length
size: petal_length
color: species
- color_discrete_map: {"setosa": "#00b4ff", "versicolor": "#ff9222"}
+ color_discrete_map: {setosa: '#00b4ff', versicolor: '#ff9222'}
id: scatter_chart
type: graph
- figure:
@@ -155,23 +156,22 @@ If you want to change nested parameters, you can specify the `targets` argument
x: sepal_width
y: sepal_length
color: species
- color_discrete_map: {"setosa": "#00b4ff", "versicolor": "#ff9222"}
+ color_discrete_map: {setosa: '#00b4ff', versicolor: '#ff9222'}
id: bar_chart
type: graph
controls:
- selector:
- options: ["#ff5267", "#3949ab"]
+ options: ['#ff5267', '#3949ab']
value: #3949ab
- multi: False
+ multi: false
type: dropdown
- targets: ["scatter_chart.color_discrete_map.virginica", "bar_chart.color_discrete_map.virginica"]
+ targets: [scatter_chart.color_discrete_map.virginica, bar_chart.color_discrete_map.virginica]
type: parameter
title: My first page
```
- === "Result"
- [![Nested]][Nested]
- [Nested]: ../../assets/user_guides/control/control5.png
+ === "Result"
+ [![Nested]][nested]
In the above example, the object passed to the function argument `color_discrete_map` is a dictionary which maps the different flower species to fixed colors (for example, `{"virginica":"blue"}`). In this case, only the value `blue` should be changed instead of the entire dictionary. This can be achieved by specifying a target as `scatter.color_discrete_map.virginica`.
@@ -180,3 +180,6 @@ Note that in the above example, one parameter affects multiple targets.
## Dynamic data parameters
If you use [dynamic data](data.md/#dynamic-data) that can be updated while the dashboard is running then you can pass parameters to the dynamic data function to alter the data loaded into your dashboard. For detailed instructions, refer to the section on [parametrized data loading](data.md/#parametrize-data-loading).
+
+[nested]: ../../assets/user_guides/control/control5.png
+[parameter]: ../../assets/user_guides/control/control4.png
diff --git a/vizro-core/docs/pages/user-guides/run.md b/vizro-core/docs/pages/user-guides/run.md
index df52e8c14..028eb5027 100644
--- a/vizro-core/docs/pages/user-guides/run.md
+++ b/vizro-core/docs/pages/user-guides/run.md
@@ -15,7 +15,6 @@ Most of our examples have a link below the code, [Run and edit this code in PyCa
You can use [PyCafe](https://py.cafe/snippet/vizro/v1) snippet mode to experiment with your own Vizro dashboards by dropping code into a new project.
-
## Default built-in Flask development server
!!! example "Default built-in Flask development server"
@@ -38,9 +37,10 @@ You can use [PyCafe](https://py.cafe/snippet/vizro/v1) snippet mode to experimen
Vizro().build(dashboard).run()
```
+
1. create a Python file named `app.py`.
-2. type the command `python app.py` into your terminal.
-3. information below will be displayed in your terminal, go to [http://127.0.0.1:8050/](http://127.0.0.1:8050/).
+1. type the command `python app.py` into your terminal.
+1. information below will be displayed in your terminal, go to [http://127.0.0.1:8050/](http://127.0.0.1:8050/).
```
Dash is running on http://127.0.0.1:8050/
@@ -51,8 +51,7 @@ INFO:werkzeug:WARNING: This is a development server. Do not use it in a producti
```
!!! warning "In production"
-
- As per the above warning message, which is [further explained in the Flask documentation](https://flask.palletsprojects.com/en/3.0.x/deploying/), the Flask development server is intended for use only during local development and **should not** be used when deploying to production. Instead, you should instead use a production-ready solution such as [Gunicorn](#gunicorn).
+ The above warning message is [further explained in the Flask documentation](https://flask.palletsprojects.com/en/3.0.x/deploying/). The Flask development server is intended for use only during local development and **should not** be used when deploying to production. Instead, you should instead use a production-ready solution such as [Gunicorn](#gunicorn).
### Automatic reloading and debugging
@@ -64,11 +63,11 @@ Setting `debug=True` enables [Dash Dev Tools](https://dash.plotly.com/devtools).
In addition, some errors generated at run time can also be viewed via the browser console (for example in `Chrome` see `View > Developer > Developer Tools > Console`).
-
## Jupyter
+
The dashboard application can be launched in a Jupyter environment in `inline`, `external`, and `jupyterlab` mode.
-!!! example "Run in a Jupyter Notebook in inline mode"
+!!! example "Run in a Jupyter Notebook in inline mode"
=== "app.ipynb"
```py linenums="1"
from vizro import Vizro
@@ -87,16 +86,16 @@ The dashboard application can be launched in a Jupyter environment in `inline`,
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run(jupyter_mode="external")
```
+
- by default, the mode is set to `inline` in `run()` and the dashboard will be displayed inside your Jupyter environment.
- you can specify `jupyter_mode="external"` and a link will be displayed to direct you to the localhost where the dashboard is running.
- you can use tab mode by `jupyter_mode="tab"` to automatically open the app in a new browser
!!! note "Reloading and debugging"
-
Code reloading and hot reloading do not work within a Jupyter Notebook. Instead, there are two methods to reload the dashboard:
- * Restart the Jupyter kernel and re-run your notebook.
- * Add a cell containing `from vizro import Vizro; Vizro._reset()` to the top of your notebook and re-run it. With this method, there is no need to restart the Jupyter kernel.
+ - Restart the Jupyter kernel and re-run your notebook.
+ - Add a cell containing `from vizro import Vizro; Vizro._reset()` to the top of your notebook and re-run it. With this method, there is no need to restart the Jupyter kernel.
## Gunicorn
@@ -126,17 +125,18 @@ The dashboard application can be launched in a Jupyter environment in `inline`,
```
1. The Vizro `app` object is a WSGI application that exposes the underlying Flask app; this will be used by Gunicorn.
- 2. Enable the same app to still be run using the built-in Flask server with `python app.py` for development purposes.
+ 1. Enable the same app to still be run using the built-in Flask server with `python app.py` for development purposes.
To run using Gunicorn with four worker processes, execute
+
```bash
gunicorn app:app --workers 4
```
+
in the command line. For more Gunicorn configuration options, refer to [Gunicorn documentation](https://docs.gunicorn.org/).
!!! warning "In production"
-
- If your dashboard uses [dynamic data](data.md#dynamic-data) that can be refreshed while the dashboard is running then you should [configure your data manager cache](data.md#configure-cache) to use a backend that supports multiple processes.
+ If your dashboard uses [dynamic data](data.md#dynamic-data) that can be refreshed while the dashboard is running then you should [configure your data manager cache](data.md#configure-cache) to use a back end that supports multiple processes.
## Deployment
@@ -149,6 +149,6 @@ Internally, `app = Vizro()` contains a Flask app in `app.dash.server`. However,
[`Vizro`][vizro.Vizro] accepts `**kwargs` that are passed through to `Dash`. This enables you to configure the underlying Dash app using the same [arguments that are available](https://dash.plotly.com/reference#dash.dash) in `Dash`. For example, in a deployment context, these arguments may be useful:
-- `url_base_pathname`: serve your Vizro app at a specific path rather than at the domain root. For example, if you host your dashboard at http://www.example.com/my_dashboard/ then you would set `url_base_pathname="/my_dashboard/"` or an environment variable `DASH_URL_BASE_PATHNAME="/my_dashboard/"`.
+- `url_base_pathname`: serve your Vizro app at a specific path rather than at the domain root. For example, if you host your dashboard at `http://www.example.com/my_dashboard/` then you would set `url_base_pathname="/my_dashboard/"` or an environment variable `DASH_URL_BASE_PATHNAME="/my_dashboard/"`.
- `serve_locally`: set to `False` to [serve Dash component libraries from a Content Delivery Network (CDN)](https://dash.plotly.com/external-resources#serving-dash's-component-libraries-locally-or-from-a-cdn), which reduces load on the server and can improve performance. Vizro uses [jsDeliver](https://www.jsdelivr.com/) as a CDN for CSS and JavaScript sources.
- `assets_external_path`: when `serve_locally=False`, you can also set `assets_external_path` or an environment variable `DASH_ASSETS_EXTERNAL_PATH` to [serve your own assets from a CDN](https://dash.plotly.com/external-resources#load-assets-from-a-folder-hosted-on-a-cdn).
diff --git a/vizro-core/docs/pages/user-guides/selectors.md b/vizro-core/docs/pages/user-guides/selectors.md
index 10481d2ba..a1bd4be20 100644
--- a/vizro-core/docs/pages/user-guides/selectors.md
+++ b/vizro-core/docs/pages/user-guides/selectors.md
@@ -6,10 +6,7 @@ The [`Filter`][vizro.models.Filter] or the [`Parameter`][vizro.models.Parameter]
## Categorical selectors
-Within the categorical selectors, a clear distinction exists between multi-option and single-option selectors.
-For instance, the [`Checklist`][vizro.models.Checklist] functions as a multi-option selector by default while
-the [`RadioItem`][vizro.models.RadioItems] serves as a single-option selector by default. However, the
-[`Dropdown`][vizro.models.Dropdown] can function as both a multi-option or single-option selector.
+Within the categorical selectors, a clear distinction exists between multi-option and single-option selectors. For instance, the [`Checklist`][vizro.models.Checklist] functions as a multi-option selector by default while the [`RadioItem`][vizro.models.RadioItems] serves as a single-option selector by default. However, the [`Dropdown`][vizro.models.Dropdown] can function as both a multi-option or single-option selector.
For more information, refer to the API reference of the selector, or the documentation of its underlying Dash component:
@@ -18,15 +15,12 @@ For more information, refer to the API reference of the selector, or the documen
- [`RadioItems`][vizro.models.RadioItems] based on [`dcc.RadioItems`](https://dash.plotly.com/dash-core-components/radioitems)
!!! note
-
- When configuring the `options` of the categorical selectors, you can either provide:
+ When configuring the `options` of the categorical selectors, you can either give:
- a list of values `options = ['Value A', 'Value B', 'Value C']`
- or a dictionary of label-value mappings `options=[{'label': 'True', 'value': True}, {'label': 'False', 'value': False}]`
- The later is required if you want to provide different display labels to your option values or in case you want to
- provide boolean values as options. In this case, you need to provide a string label for your boolean values as
- boolean values cannot be displayed properly as labels in the underlying Dash components.
+ The later is required if you want to provide different display labels to your option values or in case you want to provide boolean values as options. In this case, you need to provide a string label for your boolean values as boolean values cannot be displayed properly as labels in the underlying Dash components.
## Numerical selectors
@@ -36,11 +30,7 @@ For more information, refer to the API reference of the selector, or the documen
- [`RangeSlider`][vizro.models.RangeSlider] based on [`dcc.RangeSlider`](https://dash.plotly.com/dash-core-components/rangeslider)
!!! note
-
- When configuring the [`Slider`][vizro.models.Slider] and the [`RangeSlider`][vizro.models.RangeSlider] with float values, and using `step` with an integer value, you may notice
- unexpected behavior, such as the drag value being outside its indicated marks.
- To our knowledge, this is a current bug in the underlying [`dcc.Slider`](https://dash.plotly.com/dash-core-components/slider) and
- [`dcc.RangeSlider`](https://dash.plotly.com/dash-core-components/rangeslider) component, which you can circumvent by adapting the `step` size accordingly.
+ When configuring the [`Slider`][vizro.models.Slider] and the [`RangeSlider`][vizro.models.RangeSlider] with float values, and using `step` with an integer value, you may notice unexpected behavior, such as the drag value being outside its indicated marks. To our knowledge, this is a current bug in the underlying [`dcc.Slider`](https://dash.plotly.com/dash-core-components/slider) and [`dcc.RangeSlider`](https://dash.plotly.com/dash-core-components/rangeslider) component, which you can circumvent by adapting the `step` size as needed.
## Temporal selectors
@@ -49,7 +39,6 @@ For more information, refer to the API reference of the selector, or the documen
- [`DatePicker`][vizro.models.DatePicker] based on [`dmc.DateRangePicker`](https://www.dash-mantine-components.com/components/datepicker#daterangepicker) and [`dmc.DatePicker`](https://www.dash-mantine-components.com/components/datepicker)
!!! note
-
When the [`DatePicker`][vizro.models.DatePicker] is configured with `range=True` (the default), the underlying component is `dmc.DateRangePicker`. When `range=False` the underlying component is `dmc.DatePicker`.
When configuring the [`DatePicker`][vizro.models.DatePicker] make sure to provide your dates for `min`, `max` and `value` arguments in `"yyyy-mm-dd"` format or as `datetime` type (for example, `datetime.datetime(2024, 01, 01)`).
diff --git a/vizro-core/docs/pages/user-guides/table.md b/vizro-core/docs/pages/user-guides/table.md
index 19197c465..80e8e53dc 100755
--- a/vizro-core/docs/pages/user-guides/table.md
+++ b/vizro-core/docs/pages/user-guides/table.md
@@ -2,46 +2,32 @@
This guide shows you how to visualize tables in Vizro.
-There are two ways to visualize tables in Vizro, using either [AG Grid](#ag-grid) or [Dash DataTable](#dash-datatable).
-In general, [AG Grid](#ag-grid) is Vizro's recommended table implementation, but sometimes it may make sense to use the [Dash DataTable](#dash-datatable) instead.
+There are two ways to visualize tables in Vizro, using either [AG Grid](#ag-grid) or [Dash DataTable](#dash-datatable). In general, [AG Grid](#ag-grid) is Vizro's recommended table implementation, but sometimes it may make sense to use the [Dash DataTable](#dash-datatable) instead.
## Choose between AG Grid and Dash DataTable
-Vizro offers two models - the [`AgGrid`][vizro.models.AgGrid] model and the [`Table`][vizro.models.Table] model - for the above two approaches respectively.
-They both visualize tabular data in similar ways.
+Vizro offers two models - the [`AgGrid`][vizro.models.AgGrid] model and the [`Table`][vizro.models.Table] model - for the above two approaches respectively. They both visualize tabular data in similar ways.
-The main difference between the two is that the [`AgGrid`][vizro.models.AgGrid] model is based on Plotly's [Dash AG Grid](https://dash.plotly.com/dash-ag-grid) component,
-while the [`Table`][vizro.models.Table] model is based on the [Dash DataTable](https://dash.plotly.com/datatable) component.
-
-Both approaches have similar base features, and are configurable in similar ways. However, the AG Grid offers more advanced features out-of-the-box, is more customizable
-and also ships a powerful enterprise version. This is why it is Vizro's recommended table implementation. At the same time, the Dash DataTable can be used if developers are
-already familiar with it, or if some custom functionality is easier to implement using the Dash DataTable.
+The main difference between the two is that the [`AgGrid`][vizro.models.AgGrid] model is based on Plotly's [Dash AG Grid](https://dash.plotly.com/dash-ag-grid) component, while the [`Table`][vizro.models.Table] model is based on the [Dash DataTable](https://dash.plotly.com/datatable) component.
+Both approaches have similar base features, and are configurable in similar ways. However, the AG Grid offers more advanced features out-of-the-box, is more customizable and also ships a powerful enterprise version. This is why it is Vizro's recommended table implementation. At the same time, the Dash DataTable can be used if developers are already familiar with it, or if some custom functionality is easier to implement using the Dash DataTable.
## AG Grid
-[AG Grid](https://www.ag-grid.com/) is an interactive table/grid component designed for viewing, editing, and exploring large datasets. It
-is Vizro's recommended table implementation.
+[AG Grid](https://www.ag-grid.com/) is an interactive table/grid component designed for viewing, editing, and exploring large datasets. It is Vizro's recommended table implementation.
-The Vizro [`AgGrid`][vizro.models.AgGrid] model is based on the [Dash AG Grid](https://dash.plotly.com/dash-ag-grid), which is in turn based the
-original [Javascript implementation](https://www.ag-grid.com/).
+The Vizro [`AgGrid`][vizro.models.AgGrid] model is based on the [Dash AG Grid](https://dash.plotly.com/dash-ag-grid), which is in turn based the original [Javascript implementation](https://www.ag-grid.com/).
### Basic usage
To add a [`AgGrid`][vizro.models.AgGrid] to your page, do the following:
-1. Insert the [`AgGrid`][vizro.models.AgGrid] model into the `components` argument of the
-[`Page`][vizro.models.Page] model.
-2. Enter the `dash_ag_grid` function under the `figure` argument (imported via `from vizro.tables import dash_ag_grid`).
-
-The Vizro version of this AG Grid differs in one way from the original Dash AG Grid: it requires the user to pass a pandas DataFrame as the source of data.
-As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`. Most other [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments.
-Note that some defaults are set for some arguments (for example, for `columnDefs`) to help with styling and usability.
-Sometimes a parameter may not work because it requires a callback to function. In that case you can try [creating a custom AG Grid callable](custom-tables.md).
+1. Insert the [`AgGrid`][vizro.models.AgGrid] model into the `components` argument of the [`Page`][vizro.models.Page] model.
+1. Enter the `dash_ag_grid` function under the `figure` argument (imported via `from vizro.tables import dash_ag_grid`).
+The Vizro version of this AG Grid differs in one way from the original Dash AG Grid: it requires the user to pass a pandas DataFrame as the source of data. As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`. Most other [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments. Note that some defaults are set for some arguments (for example, for `columnDefs`) to help with styling and usability. Sometimes a parameter may not work because it requires a callback to function. In that case you can try [creating a custom AG Grid callable](custom-tables.md).
!!! example "Basic Dash AG Grid"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -59,29 +45,28 @@ Sometimes a parameter may not work because it requires a callback to function. I
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - figure:
- _target_: dash_ag_grid
- data_frame: gapminder
- type: ag_grid
- title: Default Dash AG Grid
+ - components:
+ - figure:
+ _target_: dash_ag_grid
+ data_frame: gapminder
+ type: ag_grid
+ title: Default Dash AG Grid
```
- === "Result"
- [![AGGrid]][AGGrid]
- [AGGrid]: ../../assets/user_guides/table/aggrid.png
+ === "Result"
+ [![AGGrid]][aggrid]
### Enable pagination
-Pagination is a visual alternative to using vertical scroll. It can also improve loading time if you have many rows.
-You can turn it on by setting `dashGridOptions={"pagination": True}`.
-!!! example "Basic Dash AG Grid"
+Pagination is a visual alternative to using vertical scroll. It can also improve loading time if you have many rows. You can turn it on by setting `dashGridOptions={"pagination": True}`.
+!!! example "Basic Dash AG Grid"
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -99,37 +84,34 @@ You can turn it on by setting `dashGridOptions={"pagination": True}`.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - figure:
- _target_: dash_ag_grid
- data_frame: gapminder
- dashGridOptions:
- pagination: true
- type: ag_grid
- title: Dash AG Grid with pagination
+ - components:
+ - figure:
+ _target_: dash_ag_grid
+ data_frame: gapminder
+ dashGridOptions:
+ pagination: true
+ type: ag_grid
+ title: Dash AG Grid with pagination
```
- === "Result"
- [![AGGrid]][AGGrid]
- [AGGrid]: ../../assets/user_guides/table/aggrid-pagination.png
+ === "Result"
+ [![AGGrid]][aggrid]
### Formatting columns
#### Numbers
-One of the most common tasks when working with tables is to format the columns so that displayed numbers are more readable.
-To do this, you can use the native functionality of [value formatters](https://dash.plotly.com/dash-ag-grid/value-formatters)
-or the Vizro pre-defined [custom cell data types](https://dash.plotly.com/dash-ag-grid/cell-data-types#providing-custom-cell-data-types) as shown below.
+One of the most common tasks when working with tables is to format the columns so that displayed numbers are more readable. To do this, you can use the native functionality of [value formatters](https://dash.plotly.com/dash-ag-grid/value-formatters) or the Vizro pre-defined [custom cell data types](https://dash.plotly.com/dash-ag-grid/cell-data-types#providing-custom-cell-data-types) as shown below.
The available custom cell types for Vizro are `dollar`, `euro`, `percent` and `numeric`.
-To use these, define your desired `` alongside the chosen `cellDataType` in
-the `columnDefs` argument of your `dash_ag_grid` function:
+To use these, define your desired `` alongside the chosen `cellDataType` in the `columnDefs` argument of your `dash_ag_grid` function:
```py
columnDefs = [{"field": "", "cellDataType": "euro"}]
@@ -138,7 +120,6 @@ columnDefs = [{"field": "", "cellDataType": "euro"}]
In the example below we select and format some columns of the gapminder data.
!!! example "AG Grid with formatted columns"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -168,6 +149,7 @@ In the example below we select and format some columns of the gapminder data.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -190,33 +172,23 @@ In the example below we select and format some columns of the gapminder data.
type: ag_grid
title: Example of AG Grid with formatted columns
```
- === "Result"
- [![AGGrid2]][AGGrid2]
- [AGGrid2]: ../../assets/user_guides/table/formatted_aggrid.png
+ === "Result"
+ [![AGGrid2]][aggrid2]
#### Dates
-For the [`AgGrid`][vizro.models.AgGrid] model to sort and filter dates correctly, the date must either be of
-string format `yyyy-mm-dd` (see [Dash AG Grid docs](https://dash.plotly.com/dash-ag-grid/date-filters#example:-date-filter))
-or a pandas datetime object. Any pandas datetime column will be transformed into the `yyyy-mm-dd` format automatically.
+For the [`AgGrid`][vizro.models.AgGrid] model to sort and filter dates correctly, the date must either be of string format `yyyy-mm-dd` (see [Dash AG Grid docs](https://dash.plotly.com/dash-ag-grid/date-filters#example:-date-filter)) or a pandas datetime object. Any pandas datetime column will be transformed into the `yyyy-mm-dd` format automatically.
#### Objects and strings
-No specific formatting is available for custom objects and strings, however you can make use of [Value Formatters](https://dash.plotly.com/dash-ag-grid/value-formatters)
-to format displayed strings automatically.
-
+No specific formatting is available for custom objects and strings, however you can make use of [Value Formatters](https://dash.plotly.com/dash-ag-grid/value-formatters) to format displayed strings automatically.
### Styling and changing the AG Grid
-As mentioned above, all [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments. Below you can find
-an example of a styled AG Grid where some conditional formatting is applied, and where the columns are editable, but
-not filterable or resizable. There are more ways to alter the grid beyond this showcase. AG Grid, like any other Vizro
-component, can be customized using custom CSS. You can find information in
-the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-selected-components).
+As mentioned above, all [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments. Below you can find an example of a styled AG Grid where some conditional formatting is applied, and where the columns are editable, but not filterable or resizable. There are more ways to alter the grid beyond this showcase. AG Grid, like any other Vizro component, can be customized using custom CSS. You can find information in the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-selected-components).
!!! example "Styled and modified Dash AG Grid"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -284,6 +256,7 @@ the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-select
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -299,28 +272,28 @@ the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-select
- field: year
- field: lifeExp
valueFormatter:
- function: "d3.format('.1f')(params.value)"
+ function: d3.format('.1f')(params.value)
- field: gdpPercap
valueFormatter:
- function: "d3.format('$,.1f')(params.value)"
+ function: d3.format('$,.1f')(params.value)
cellStyle:
styleConditions:
- condition: params.value < 1045
style:
- backgroundColor: "#ff9222"
+ backgroundColor: '#ff9222'
- condition: params.value >= 1045 && params.value <= 4095
style:
- backgroundColor: "#de9e75"
+ backgroundColor: '#de9e75'
- condition: params.value > 4095 && params.value <= 12695
style:
- backgroundColor: "#aaa9ba"
+ backgroundColor: '#aaa9ba'
- condition: params.value > 12695
style:
- backgroundColor: "#00b4ff"
+ backgroundColor: '#00b4ff'
- field: pop
type: rightAligned
valueFormatter:
- function: "d3.format(',.0f')(params.value)"
+ function: d3.format(',.0f')(params.value)
defaultColDef:
resizable: false
filter: false
@@ -329,10 +302,9 @@ the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-select
type: ag_grid
title: Example of a Dash AG Grid
```
- === "Result"
- [![AGGrid3]][AGGrid3]
- [AGGrid3]: ../../assets/user_guides/table/styled_aggrid.png
+ === "Result"
+ [![AGGrid3]][aggrid3]
If the available arguments are not sufficient, there is always the option to [create a custom AG Grid callable](custom-tables.md).
@@ -348,19 +320,14 @@ The Vizro [`Table`][vizro.models.Table] model is based on the [Dash DataTable](h
To add a [`Table`][vizro.models.Table] to your page, do the following:
-1. Insert the [`Table`][vizro.models.Table] model into the `components` argument of the
-[`Page`][vizro.models.Page] model.
-2. Enter the `dash_data_table` function under the `figure` argument (imported via `from vizro.tables import dash_data_table`).
-
+1. Insert the [`Table`][vizro.models.Table] model into the `components` argument of the [`Page`][vizro.models.Page] model.
+1. Enter the `dash_data_table` function under the `figure` argument (imported via `from vizro.tables import dash_data_table`).
-The Vizro version of this table differs in one way from the original table: it requires the user to pass a pandas DataFrame as the source of data.
-As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`.
+The Vizro version of this table differs in one way from the original table: it requires the user to pass a pandas DataFrame as the source of data. As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`.
-All other [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Note that we are
-setting some defaults for some arguments to help with styling.
+All other [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Note that we are setting some defaults for some arguments to help with styling.
!!! example "Dash DataTable"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -380,31 +347,29 @@ setting some defaults for some arguments to help with styling.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: dash_data_table
- data_frame: gapminder_2007
- title: Dash DataTable
- type: table
- title: Example of a Dash DataTable
+ - components:
+ - figure:
+ _target_: dash_data_table
+ data_frame: gapminder_2007
+ title: Dash DataTable
+ type: table
+ title: Example of a Dash DataTable
```
- === "Result"
- [![Table]][Table]
- [Table]: ../../assets/user_guides/table/table.png
+ === "Result"
+ [![Table]][table]
### Styling and changing the Dash DataTable
-As mentioned above, all [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Below you can find
-an example of a styled table where some conditional formatting is applied. There are many more ways to alter the table beyond this showcase.
+As mentioned above, all [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Below you can find an example of a styled table where some conditional formatting is applied. There are many more ways to alter the table beyond this showcase.
!!! example "Styled Dash DataTable"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -467,6 +432,7 @@ an example of a styled table where some conditional formatting is applied. There
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -504,12 +470,12 @@ an example of a styled table where some conditional formatting is applied. There
backgroundColor: dodgerblue
color: white
- if:
- filter_query: "{lifeExp} < 55"
+ filter_query: '{lifeExp} < 55'
column_id: lifeExp
- backgroundColor: "#85144b"
+ backgroundColor: '#85144b'
color: white
- if:
- filter_query: "{gdpPercap} > 10000"
+ filter_query: '{gdpPercap} > 10000'
column_id: gdpPercap
backgroundColor: green
color: white
@@ -524,26 +490,20 @@ an example of a styled table where some conditional formatting is applied. There
title: Dash DataTable
```
- === "Result"
- [![Table2]][Table2]
- [Table2]: ../../assets/user_guides/table/styled_table.png
+ === "Result"
+ [![Table2]][table2]
If the available arguments are not sufficient, there is always the option to create a [custom Dash DataTable](custom-tables.md).
-
## Add title, header, and footer
-The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] models accept a `title`, `header` and
-`footer` argument. This is useful for providing context to the data being displayed, or for adding a description of
-the data.
+The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] models accept a `title`, `header` and `footer` argument. This is useful for providing context to the data being displayed, or for adding a description of the data.
- **title**: Displayed as an [H3 header](https://dash.plotly.com/dash-html-components/h3), useful for summarizing the main topic or insight of the component.
- **header**: Accepts markdown text, ideal for extra descriptions, subtitles, or detailed data insights.
- **footer**: Accepts markdown text, commonly used for citing data sources, providing information on the last update, or adding disclaimers.
-
-
### Formatted AgGrid
!!! example "Formatted AgGrid"
@@ -571,30 +531,29 @@ the data.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: dash_ag_grid
- data_frame: gapminder_2007
- dashGridOptions:
- pagination: true
- title: Gapminder Data Insights
- header: |
- #### An Interactive Exploration of Global Health, Wealth, and Population
- footer: |
- SOURCE: **Plotly gapminder data set, 2024**
- type: ag_grid
- title: Formatted AgGrid
+ - components:
+ - figure:
+ _target_: dash_ag_grid
+ data_frame: gapminder_2007
+ dashGridOptions:
+ pagination: true
+ title: Gapminder Data Insights
+ header: |
+ #### An Interactive Exploration of Global Health, Wealth, and Population
+ footer: |
+ SOURCE: **Plotly gapminder data set, 2024**
+ type: ag_grid
+ title: Formatted AgGrid
```
- === "Result"
- [![FormattedGrid]][FormattedGrid]
-
- [FormattedGrid]: ../../assets/user_guides/components/formatted_aggrid.png
+ === "Result"
+ [![FormattedGrid]][formattedgrid]
### Formatted DataTable
@@ -623,24 +582,32 @@ the data.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: dash_data_table
- data_frame: gapminder_2007
- title: Gapminder Data Insights
- header: |
- #### An Interactive Exploration of Global Health, Wealth, and Population
- footer: |
- SOURCE: **Plotly gapminder data set, 2024**
- type: table
- title: Formatted DataTable
+ - components:
+ - figure:
+ _target_: dash_data_table
+ data_frame: gapminder_2007
+ title: Gapminder Data Insights
+ header: |
+ #### An Interactive Exploration of Global Health, Wealth, and Population
+ footer: |
+ SOURCE: **Plotly gapminder data set, 2024**
+ type: table
+ title: Formatted DataTable
```
- === "Result"
- [![FormattedTable]][FormattedTable]
- [FormattedTable]: ../../assets/user_guides/components/formatted_table.png
+ === "Result"
+ [![FormattedTable]][formattedtable]
+
+[aggrid]: ../../assets/user_guides/table/aggrid.png
+[aggrid2]: ../../assets/user_guides/table/formatted_aggrid.png
+[aggrid3]: ../../assets/user_guides/table/styled_aggrid.png
+[formattedgrid]: ../../assets/user_guides/components/formatted_aggrid.png
+[formattedtable]: ../../assets/user_guides/components/formatted_table.png
+[table]: ../../assets/user_guides/table/table.png
+[table2]: ../../assets/user_guides/table/styled_table.png
diff --git a/vizro-core/docs/pages/user-guides/tabs.md b/vizro-core/docs/pages/user-guides/tabs.md
index 09154177e..1811d0cac 100755
--- a/vizro-core/docs/pages/user-guides/tabs.md
+++ b/vizro-core/docs/pages/user-guides/tabs.md
@@ -1,8 +1,6 @@
# How to use tabs
-[`Tabs`][vizro.models.Tabs] organize and separate groups of related content in a dashboard, letting users switch between different sections or views.
-They are essentially a way of putting multiple [`Containers`][vizro.models.Container] in the same screen space, and letting the user switch between them.
-`Containers` enable the grouping of page components into sections and subsections. See our [user guide on `Containers`](container.md) for more information.
+[`Tabs`][vizro.models.Tabs] organize and separate groups of related content in a dashboard, letting users switch between different sections or views. They are essentially a way of putting multiple [`Containers`][vizro.models.Container] in the same screen space, and letting the user switch between them. `Containers` enable the grouping of page components into sections and subsections. See our [user guide on `Containers`](container.md) for more information.
{ width="400"}
@@ -16,14 +14,12 @@ This guide shows you how to use tabs to organize your `Containers` into subsecti
By using [`Tabs`][vizro.models.Tabs], the following applies:
- [`Filters`][vizro.models.Filter] affect all components on all tabs (opened and closed) of the page if not specified otherwise inside `Filter.targets`
-- The `title` of the [`Container`][vizro.models.Container] inserted into `Tabs.tabs` will be displayed as a tab label, and the title will be removed from the `Container`
-
+- The `title` of the [`Container`][vizro.models.Container] inserted into `Tabs.tabs` will be displayed as a tab label, and the title will be removed from the `Container`
To add [`Tabs`][vizro.models.Tabs] to your page, do the following:
1. Insert the [`Tabs`][vizro.models.Tabs] into the `components` argument of the [`Page`][vizro.models.Page]
-2. Insert your [`Containers`][vizro.models.Container] into the `tabs` argument of the [`Tabs`][vizro.models.Tabs]
-
+1. Insert your [`Containers`][vizro.models.Container] into the `tabs` argument of the [`Tabs`][vizro.models.Tabs]
!!! example "Tabs"
=== "app.py"
@@ -88,52 +84,53 @@ To add [`Tabs`][vizro.models.Tabs] to your page, do the following:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - tabs:
- - title: Tab I
- type: container
- components:
- - type: graph
- figure:
- _target_: bar
- data_frame: gapminder_2007
- title: Graph 1
- x: continent
- y: lifeExp
- color: continent
- - type: graph
- figure:
- _target_: box
- data_frame: gapminder_2007
- title: Graph 2
- x: continent
- y: lifeExp
- color: continent
- - title: Tab II
- type: container
- components:
- - type: graph
- figure:
- _target_: scatter
- data_frame: gapminder_2007
- title: Graph 3
- x: gdpPercap
- y: lifeExp
- size: pop
- color: continent
- type: tabs
+ components:
+ - type: tabs
+ tabs:
+ - title: Tab I
+ type: container
+ components:
+ - type: graph
+ figure:
+ _target_: bar
+ data_frame: gapminder_2007
+ title: Graph 1
+ x: continent
+ y: lifeExp
+ color: continent
+ - type: graph
+ figure:
+ _target_: box
+ data_frame: gapminder_2007
+ title: Graph 2
+ x: continent
+ y: lifeExp
+ color: continent
+ - title: Tab II
+ type: container
+ components:
+ - type: graph
+ figure:
+ _target_: scatter
+ data_frame: gapminder_2007
+ title: Graph 3
+ x: gdpPercap
+ y: lifeExp
+ size: pop
+ color: continent
controls:
- - type: filter
- column: continent
+ - type: filter
+ column: continent
title: Tabs
```
- === "Result"
- [![Tabs]][Tabs]
+ === "Result"
+ [![Tabs]][tabs]
- [Tabs]: ../../assets/user_guides/components/tabs.png
+[tabs]: ../../assets/user_guides/components/tabs.png
diff --git a/vizro-core/docs/pages/user-guides/themes.md b/vizro-core/docs/pages/user-guides/themes.md
index 6f78441d5..ac1d6fc7b 100644
--- a/vizro-core/docs/pages/user-guides/themes.md
+++ b/vizro-core/docs/pages/user-guides/themes.md
@@ -1,15 +1,13 @@
# How to use themes
-This guide shows you how to use themes. Themes are pre-designed collections of stylings that are applied to entire charts and dashboards.
-The themes provided by Vizro are infused with our design best practices that make charts and dashboards look visually consistent and professional.
+This guide shows you how to use themes. Themes are pre-designed collections of stylings that are applied to entire charts and dashboards. The themes provided by Vizro are infused with our design best practices that make charts and dashboards look visually consistent and professional.
## Themes in dashboards
-The [`Dashboard`][vizro.models.Dashboard] model accepts an optional `theme` argument, where you can choose between
-a `vizro_dark` and a `vizro_light` theme. If not specified then `theme` defaults to `vizro_dark`. The theme is applied to the entire dashboard and its charts/components when a user first loads your dashboard. Regardless of the theme applied on first load, users can always switch between light and dark themes via the toggle button in the upper-right corner of the dashboard.
+
+The [`Dashboard`][vizro.models.Dashboard] model accepts an optional `theme` argument, where you can choose between a `vizro_dark` and a `vizro_light` theme. If not specified then `theme` defaults to `vizro_dark`. The theme is applied to the entire dashboard and its charts/components when a user first loads your dashboard. Regardless of the theme applied on first load, users can always switch between light and dark themes via the toggle button in the upper-right corner of the dashboard.
!!! example "Change theme"
=== "app.py"
-
```{.python pycafe-link hl_lines="18"}
import vizro.models as vm
import vizro.plotly.express as px
@@ -32,47 +30,40 @@ a `vizro_dark` and a `vizro_light` theme. If not specified then `theme` defaults
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml hl_lines="12"
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: scatter_matrix
- color: species
- data_frame: iris
- dimensions: ["sepal_length", "sepal_width", "petal_length", "petal_width"]
- type: graph
- title: Changing themes
+ - components:
+ - figure:
+ _target_: scatter_matrix
+ color: species
+ data_frame: iris
+ dimensions: [sepal_length, sepal_width, petal_length, petal_width]
+ type: graph
+ title: Changing themes
theme: vizro_light
```
+
=== "Result - vizro_light"
- [![Light]][Light]
+ [![Light]][light]
- [Light]: ../../assets/user_guides/themes/light.png
=== "Result - vizro_dark"
- [![Dark]][Dark]
-
- [Dark]: ../../assets/user_guides/themes/dark.png
-
+ [![Dark]][dark]
## Themes in plotly charts
You can also use our templates for plotly charts outside the dashboard. This is useful in a few contexts:
-* Creation of standalone charts to be used independently of a Vizro dashboard.
-* Rapid development of charts for eventual use in a Vizro dashboard, for example in a Jupyter Notebook.
+- Creation of standalone charts to be used independently of a Vizro dashboard.
+- Rapid development of charts for eventual use in a Vizro dashboard, for example in a Jupyter Notebook.
!!! note
+ Using `import vizro.plotly.express as px` is equal to using `import plotly.express as px`, but with the added benefit of being able to integrate the resulting chart code into a Vizro dashboard. Vizro offers a minimal layer on top of Plotly's existing charting library, allowing you to seamlessly use all the existing charts and functionalities provided by plotly.express without any modifications.
- Using `import vizro.plotly.express as px` is equivalent to using `import plotly.express as px`,
- but with the added benefit of being able to integrate the resulting chart code into a Vizro dashboard.
- Vizro offers a minimal layer on top of Plotly's existing charting library, allowing you to seamlessly use all the
- existing charts and functionalities provided by plotly.express without any modifications.
-
-Our `vizro_dark` and `vizro_light` themes are automatically registered to `plotly.io.templates` when importing Vizro.
-Consult the plotly documentation for [more details on how templates work in plotly](https://plotly.com/python/templates/#theming-and-templates).
+Our `vizro_dark` and `vizro_light` themes are automatically registered to `plotly.io.templates` when importing Vizro. Consult the plotly documentation for [more details on how templates work in plotly](https://plotly.com/python/templates/#theming-and-templates).
By default, plots imported from `vizro.plotly.express` have the `vizro_dark` theme applied. This can be altered either globally or for individual plots.
@@ -87,14 +78,20 @@ pio.templates.default = "vizro_light"
```
### Set themes for selected charts
+
To change the template for a selected chart only, use the `template` parameter and run:
```python
import vizro.plotly.express as px
df = px.data.iris()
-px.scatter_matrix(df,
- dimensions=["sepal_length", "sepal_width", "petal_length", "petal_width"],
- color="species",
- template="vizro_light")
+px.scatter_matrix(
+ df,
+ dimensions=["sepal_length", "sepal_width", "petal_length", "petal_width"],
+ color="species",
+ template="vizro_light",
+)
```
+
+[dark]: ../../assets/user_guides/themes/dark.png
+[light]: ../../assets/user_guides/themes/light.png
diff --git a/vizro-core/docs/pages/user-guides/visual-formatting.md b/vizro-core/docs/pages/user-guides/visual-formatting.md
index 7b384f3e9..56d1d2d52 100644
--- a/vizro-core/docs/pages/user-guides/visual-formatting.md
+++ b/vizro-core/docs/pages/user-guides/visual-formatting.md
@@ -1,17 +1,13 @@
# How to customize the style of Vizro dashboards
-Vizro has a default styling to help users with no design experience get started.
-There are several options if you want to customize the style:
+Vizro has a default styling to help users with no design experience get started. There are several options if you want to customize the style:
-* **[Configure the `Layout`](layouts.md)**: Customize the arrangement of your components inside your Vizro dashboard.
+- **[Configure the `Layout`](layouts.md)**: Customize the arrangement of your components inside your Vizro dashboard.
-* **[Apply a theme](themes.md)**: Choose between a dark or light theme.
+- **[Apply a theme](themes.md)**: Choose between a dark or light theme.
-* **[Manage assets](assets.md)**: Enhance your dashboard by adding images, scripts, and stylesheets to your assets folder.
+- **[Manage assets](assets.md)**: Enhance your dashboard by adding images, scripts, and stylesheets to your assets folder.
-* **[Customize CSS](custom-css.md)**: Incorporate custom CSS to deviate from the default styling and create a
-unique appearance for your Vizro dashboard.
+- **[Customize CSS](custom-css.md)**: Incorporate custom CSS to deviate from the default styling and create a unique appearance for your Vizro dashboard.
-* **[Customize your `component`](components.md)**: Change the appearance of components like the [Graph](graph.md), the
-[Table](table.md) and the [AgGrid](table.md), by passing extra arguments. Refer to the relevant user guide for
-more details.
+- **[Customize your `component`](components.md)**: Change the appearance of components like the [Graph](graph.md), the [Table](table.md) and the [AgGrid](table.md), by passing extra arguments. Refer to the relevant user guide for more details.
diff --git a/vizro-core/examples/README.md b/vizro-core/examples/README.md
index 72146bfb7..53cf932b7 100644
--- a/vizro-core/examples/README.md
+++ b/vizro-core/examples/README.md
@@ -4,8 +4,7 @@ Please note that this folder contains only example dashboards that are still **i
### Vizro examples gallery
-To view a comprehensive list of available demos, please visit our [examples gallery](http://vizro.mckinsey.com/).
-There, you can explore a wide range of dashboards and applications created with Vizro.
+To view a comprehensive list of available demos, please visit our [examples gallery](http://vizro.mckinsey.com/). There, you can explore a wide range of dashboards and applications created with Vizro.
diff --git a/vizro-core/examples/visual-vocabulary/README.md b/vizro-core/examples/visual-vocabulary/README.md
index 3b298520e..e59b3103c 100644
--- a/vizro-core/examples/visual-vocabulary/README.md
+++ b/vizro-core/examples/visual-vocabulary/README.md
@@ -2,14 +2,11 @@
### Welcome to our visual vocabulary dashboard! 🎨
-This dashboard serves as a comprehensive guide for selecting and creating various types of charts. It helps you decide
-when to use each chart type, and offers sample Python code using [Plotly](https://plotly.com/python/), and
-instructions for embedding these charts into a [Vizro](https://github.com/mckinsey/vizro) dashboard.
+This dashboard serves as a comprehensive guide for selecting and creating various types of charts. It helps you decide when to use each chart type, and offers sample Python code using [Plotly](https://plotly.com/python/), and instructions for embedding these charts into a [Vizro](https://github.com/mckinsey/vizro) dashboard.
The charts in this dashboard are designed to make it easy for anyone to create beautiful and sophisticated visuals.
-Our goal is to help you understand best practices in data visualization, ensure your charts effectively communicate
-your message, and streamline the creation of high-quality, interactive visualizations.
+Our goal is to help you understand best practices in data visualization, ensure your charts effectively communicate your message, and streamline the creation of high-quality, interactive visualizations.
Created by:
@@ -19,12 +16,9 @@ Created by:
Inspired by:
-- [The FT Visual Vocabulary](https://github.com/Financial-Times/chart-doctor/blob/main/visual-vocabulary/README.md):
- [Alan Smith](https://github.com/alansmithy), [Chris Campbell](https://github.com/digitalcampbell), Ian Bott,
- Liz Faunce, Graham Parrish, Billy Ehrenberg, Paul McCallum, [Martin Stabe](https://github.com/martinstabe).
+- [The FT Visual Vocabulary](https://github.com/Financial-Times/chart-doctor/blob/main/visual-vocabulary/README.md): [Alan Smith](https://github.com/alansmithy), [Chris Campbell](https://github.com/digitalcampbell), Ian Bott, Liz Faunce, Graham Parrish, Billy Ehrenberg, Paul McCallum, [Martin Stabe](https://github.com/martinstabe).
-- [The Graphic Continuum](https://www.informationisbeautifulawards.com/showcase/611-the-graphic-continuum):
- Jon Swabish and Severino Ribecca
+- [The Graphic Continuum](https://www.informationisbeautifulawards.com/showcase/611-the-graphic-continuum): Jon Swabish and Severino Ribecca
Credits and sources:
@@ -102,13 +96,12 @@ The dashboard is still in development. Below is an overview of the chart types f
Contributions are welcome! To contribute a chart, follow the steps below:
1. Check that a `svg` file named after the chart type is contained in the [assets](https://github.com/mckinsey/vizro/tree/main/vizro-core/examples/visual-vocabulary/assets/images/charts) folder. If not, [raise an issue](https://github.com/mckinsey/vizro/issues) in the repository.
-2. Add a `.py` file containing a code example of the chart type in the `pages/examples` folder, for instance, `area.py`. Take a look at existing examples.
-3. Create a new page for the chart type and add it to the relevant category `.py` file such as `correlation.py`,
- `deviation.py`, `distribution.py`, etc. Ensure you add the page to the list of `pages` at the end of the `.py` file.
-4. Remove the `IncompletePage(..)` entry for that chart type in `chart_groups.py`.
-5. Update this `README.md` with the new chart type, its status, category, and API links.
+1. Add a `.py` file containing a code example of the chart type in the `pages/examples` folder, for instance, `area.py`. Take a look at existing examples.
+1. Create a new page for the chart type and add it to the relevant category `.py` file such as `correlation.py`, `deviation.py`, `distribution.py`, etc. Ensure you add the page to the list of `pages` at the end of the `.py` file.
+1. Remove the `IncompletePage(..)` entry for that chart type in `chart_groups.py`.
+1. Update this `README.md` with the new chart type, its status, category, and API links.
## How to run the example locally
1. Run the example with the command `hatch run example visual-vocabulary`.
-2. You should now be able to access the app locally via http://127.0.0.1:8051/.
+1. You should now be able to access the app locally via http://127.0.0.1:8051/.
+
+ #### Header level 4
+ type: card
+ - text: |
+ Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
+
+ Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
+
+ Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
+
+ Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
+ title: Paragraphs
+ type: card
+ - text: |
+ >
+ > A block quote is a long quotation, indented to create a separate block of text.
+ >
+ title: Block Quotes
+ type: card
+ - text: |
+ * Item A
+ * Sub Item 1
+ * Sub Item 2
+ * Item B
+ title: Lists
+ type: card
+ - text: |
+ This word will be *italic*
+
+ This word will be **bold**
+
+ This word will be _**bold and italic**_
+ title: Emphasis
+ type: card
+ title: Customizing Text
```
- === "Result"
- [![CardText]][CardText]
- [CardText]: ../../assets/user_guides/components/card_text.png
+ === "Result"
+ [![CardText]][cardtext]
### Place an image on a card
@@ -189,11 +185,10 @@ Images can be added to the `text` parameter by using the standard markdown synta
``
-An image ALT text offers a description to your image and serves as a text placeholder or to improve the
-accessibility of your app. Providing an image ALT text is optional.
+An image ALT text offers a description to your image and serves as a text placeholder or to improve the accessibility of your app. Providing an image ALT text is optional.
1. To use a relative Image URL, place an image of your choice into your `assets` folder first
-2. Use markdown to render your image by using one of the following syntax:
+1. Use markdown to render your image by using one of the following syntax:
- Relative Image URL: ``
- Absolute Image URL: ``
@@ -228,55 +223,50 @@ accessibility of your app. Providing an image ALT text is optional.
Run and edit this code in PyCafe
-
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - text: |
- 
+ - components:
+ - text: |
+ 
- Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
+ Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
- Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
+ Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
- Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
- title: My card with image!
- type: card
- title: Placing Images
+ Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
+ title: My card with image!
+ type: card
+ title: Placing Images
```
- === "Result"
- [![CardImageDefault]][CardImageDefault]
- [CardImageDefault]: ../../assets/user_guides/components/card_image_default.png
+ === "Result"
+ [![CardImageDefault]][cardimagedefault]
!!! note
-
- Note that inserting images using html is by default turned off by the `dcc.Markdown` to prevent users being exposed
- to cross-site scripting attacks. If you need to turn it on, a custom component would have to be created.
+ Note that inserting images using HTML is by default turned off by the `dcc.Markdown` to prevent users being exposed to cross-site scripting attacks. If you need to turn it on, a custom component would have to be created.
You might notice that the image is quite large. You'll find out how to style images in terms of their position and size in the next section.
-
### Style a card image
To change the size or position of the image, add a URL hash to your image like this:
``
-Note the added URL hash `#my-image`. Now create a CSS file placed in your `assets` folder
-and give an attribute selector to select images with that matching URL hash.
+Note the added URL hash `#my-image`. Now create a CSS file placed in your `assets` folder and give an attribute selector to select images with that matching URL hash.
!!! example "Card with styled image"
=== "images.css"
- ```css
- img[src*="#my-image"] {
- width: 120px;
- height: 120px;
- }
- ```
+ ```css
+ img[src*="#my-image"] {
+ width: 120px;
+ height: 120px;
+ }
+ ```
+
=== "app.py"
```py
import vizro.models as vm
@@ -313,23 +303,22 @@ and give an attribute selector to select images with that matching URL hash.
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - text: |
- 
+ - components:
+ - text: |
+ 
- Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
+ Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
- Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
+ Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
- Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
- title: My card with image!
- type: card
- title: Styling Images
+ Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
+ title: My card with image!
+ type: card
+ title: Styling Images
```
- === "Result"
- [![CardImageStyled]][CardImageStyled]
- [CardImageStyled]: ../../assets/user_guides/components/card_image_styled.png
+ === "Result"
+ [![CardImageStyled]][cardimagestyled]
Use the following pre-defined URL hashes in your image path to apply Vizro's default styling.
@@ -341,12 +330,13 @@ Use the following pre-defined URL hashes in your image path to apply Vizro's def
!!! example "Card with floating image"
=== "images.css"
- ```css
- img[src*="#my-image"] {
- width: 120px;
- height: 120px;
- }
- ```
+ ```css
+ img[src*="#my-image"] {
+ width: 120px;
+ height: 120px;
+ }
+ ```
+
=== "app.py"
```py
import vizro.models as vm
@@ -389,29 +379,28 @@ Use the following pre-defined URL hashes in your image path to apply Vizro's def
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - text: |
- 
+ - components:
+ - text: |
+ 
- Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
+ Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
- Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
+ Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
- Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
+ Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
- Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
+ Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
- Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
+ Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
- Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
- title: My card with floating image!
- type: card
- title: Floating Images
+ Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
+ title: My card with floating image!
+ type: card
+ title: Floating Images
```
- === "Result"
- [![CardImageFloating]][CardImageFloating]
- [CardImageFloating]: ../../assets/user_guides/components/card_image_floating.png
+ === "Result"
+ [![CardImageFloating]][cardimagefloating]
#### Card with icon
@@ -442,38 +431,34 @@ Use the following pre-defined URL hashes in your image path to apply Vizro's def
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - text: |
- 
+ - components:
+ - text: |
+ 
- ### Card Title
+ ### Card Title
- Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut fringilla dictum lacus eget fringilla.
- Maecenas in various nibh, quis venenatis nulla. Integer et libero ultrices, scelerisque velit sed.
- type: card
- title: Card with icon
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut fringilla dictum lacus eget fringilla.
+ Maecenas in various nibh, quis venenatis nulla. Integer et libero ultrices, scelerisque velit sed.
+ type: card
+ title: Card with icon
```
- === "Result"
- [![CardIcon]][CardIcon]
-
- [CardIcon]: ../../assets/user_guides/components/card_icon.png
+ === "Result"
+ [![CardIcon]][cardicon]
### Make an icon responsive to theme switch
-To make an icon responsive to the theme switch, override the value of the [`filter` CSS property](https://developer.mozilla.org/en-US/docs/Web/CSS/filter).
-The `filter` CSS property lets you add visual effects to elements using different functions. In our example, we're using the `--inverse-color` CSS variable from the Vizro theme.
-It uses the CSS `invert()` function to flip the color of the icon when you switch themes. Note that this only works if your initial icon has a white fill color. If your icon is not white, you can change its color by adding `fill="white"` to the SVG code.
-Assign the predefined CSS variable `--inverse-color` to the `filter` property of your selected icon.
+To make an icon responsive to the theme switch, override the value of the [`filter` CSS property](https://developer.mozilla.org/en-US/docs/Web/CSS/filter). The `filter` CSS property lets you add visual effects to elements using different functions. In our example, we're using the `--inverse-color` CSS variable from the Vizro theme. It uses the CSS `invert()` function to flip the color of the icon when you switch themes. Note that this only works if your initial icon has a white fill color. If your icon is not white, you can change its color by adding `fill="white"` to the SVG code. Assign the predefined CSS variable `--inverse-color` to the `filter` property of your selected icon.
```css
img[src*="#my-image"] {
- filter: var(--inverse-color);
+ filter: var(--inverse-color);
}
```
@@ -482,18 +467,15 @@ img[src*="#my-image"] {
### Create a navigation card
-This section describes how to use the [`Card`][vizro.models.Card] component to create a navigation card,
-enabling users to navigate to another page by clicking on the card area.
+This section describes how to use the [`Card`][vizro.models.Card] component to create a navigation card, enabling users to navigate to another page by clicking on the card area.
-For a button-style link navigation component, see the [separate guide on creating a link button](#create-a-link-button).
-To configure the navigation panel on the left hand side of the screen, refer to the
-[separate guide on navigation](navigation.md).
+For a button-style link navigation component, see the [separate guide on creating a link button](#create-a-link-button). To configure the navigation panel on the left hand side of the screen, refer to the [separate guide on navigation](navigation.md).
To create a navigation card:
1. Insert the [`Card`][vizro.models.Card] into the `components` argument of the [`Page`][vizro.models.Page].
-2. Pass your markdown text to the `Card.text`.
-3. Pass a relative or absolute URL to the `Card.href`.
+1. Pass your markdown text to the `Card.text`.
+1. Pass a relative or absolute URL to the `Card.href`.
!!! example "Navigation Card"
=== "app.py"
@@ -537,72 +519,65 @@ To create a navigation card:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - text: |
- ### Filters and parameters
-
- Leads to the first page on click
- href: /filters-and-parameters
- type: card
- - text: |
- ### Google - External Link
-
- Leads to an external link on click.
- href: https://google.com
- type: card
- title: Homepage
- - components:
- - figure:
- _target_: scatter
- color: sepal_width
- data_frame: iris
- x: sepal_length
- y: petal_width
- type: graph
- title: Filters and parameters
+ - components:
+ - text: |
+ ### Filters and parameters
+
+ Leads to the first page on click
+ href: /filters-and-parameters
+ type: card
+ - text: |
+ ### Google - External Link
+
+ Leads to an external link on click.
+ href: https://google.com
+ type: card
+ title: Homepage
+ - components:
+ - figure:
+ _target_: scatter
+ color: sepal_width
+ data_frame: iris
+ x: sepal_length
+ y: petal_width
+ type: graph
+ title: Filters and parameters
```
- === "Result"
- [![NavCard]][NavCard]
- [NavCard]: ../../assets/user_guides/components/nav_card.png
+ === "Result"
+ [![NavCard]][navcard]
If you now click on the card area, you should automatically be redirected to the relevant `href`.
!!! note
-
When using the [`Card`][vizro.models.Card], keep the following in mind:
- If the href given is a relative URL, it should match the `path` of the [`Page`][vizro.models.Page] that the [`Card`][vizro.models.Card] should navigate to.
- If the href given is an absolute link, it should start with `https://` or an equivalent protocol.
-
### Create a KPI card
-To create a KPI card, you can use the existing KPI card functions from [`vizro.figures`](../API-reference/figure-callables.md).
-Unlike the static text card `vm.Card`, a KPI card must be created using a figure function,
-which enables the text content of the KPI to change based on input from controls or actions.
+
+To create a KPI card, you can use the existing KPI card functions from [`vizro.figures`](../API-reference/figure-callables.md). Unlike the static text card `vm.Card`, a KPI card must be created using a figure function, which enables the text content of the KPI to change based on input from controls or actions.
For detailed examples on how to create a KPI card, refer to the [figure user guide on KPI cards](figure.md#key-performance-indicator-kpi-cards).
## Buttons
-The Button component is commonly used for interactive dashboard interactions
-such as form submissions, navigation links, and other action triggers.
-
-To add a [`Button`][vizro.models.Button], insert it into the `components` argument of the
-[`Page`][vizro.models.Page].
+The Button component is commonly used for interactive dashboard interactions such as form submissions, navigation links, and other action triggers.
+To add a [`Button`][vizro.models.Button], insert it into the `components` argument of the [`Page`][vizro.models.Page].
### Customize button text
You can configure the `text` argument to alter the display text of the [`Button`][vizro.models.Button].
!!! example "Customize text"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -616,26 +591,24 @@ You can configure the `text` argument to alter the display text of the [`Button`
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- components:
- - type: button
- text: I'm a button!
+ - type: button
+ text: I'm a button!
title: Button with text
```
- === "Result"
- [![ButtonText]][ButtonText]
-
- [ButtonText]: ../../assets/user_guides/components/button_text.png
+ === "Result"
+ [![ButtonText]][buttontext]
### Create a link button
-To navigate to a different page using a button with an anchor tag, assign an absolute or relative URL to the
-`Button.href`.
+To navigate to a different page using a button with an anchor tag, assign an absolute or relative URL to the `Button.href`.
```python
import vizro.models as vm
@@ -645,16 +618,11 @@ vm.Button(text="Leave us a star! ⭐", href="https://github.com/mckinsey/vizro")
### Attach an action
-You can use the [`Button`][vizro.models.Button] to trigger predefined action functions, such as exporting data.
-To explore the available options for [`Actions`][vizro.models.Action], refer to our [API reference][vizro.actions].
-Use the `Button.actions` argument to specify which action function executes when the button is clicked.
-
-The example below demonstrates how to configure a button to export the filtered data of a target chart using the
-[export_data][vizro.actions.export_data] action function.
+You can use the [`Button`][vizro.models.Button] to trigger predefined action functions, such as exporting data. To explore the available options for [`Actions`][vizro.models.Action], refer to our [API reference][vizro.actions]. Use the `Button.actions` argument to specify which action function executes when the button is clicked.
+The example below demonstrates how to configure a button to export the filtered data of a target chart using the [export_data][vizro.actions.export_data] action function.
!!! example "Button with action"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -690,29 +658,30 @@ The example below demonstrates how to configure a button to export the filtered
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- components:
- - figure:
- _target_: scatter
- x: sepal_width
- y: sepal_length
- color: species
- size: petal_length
- data_frame: iris
- id: scatter_chart
- type: graph
- - type: button
- text: Export data
- id: export_data
- actions:
- - function:
- _target_: export_data
- targets:
- - scatter_chart
+ - figure:
+ _target_: scatter
+ x: sepal_width
+ y: sepal_length
+ color: species
+ size: petal_length
+ data_frame: iris
+ id: scatter_chart
+ type: graph
+ - type: button
+ text: Export data
+ id: export_data
+ actions:
+ - function:
+ _target_: export_data
+ targets:
+ - scatter_chart
controls:
- column: species
selector:
@@ -728,14 +697,13 @@ The example below demonstrates how to configure a button to export the filtered
- [1]
title: My first page
```
- === "Result"
- [![Button]][Button]
- [Button]: ../../assets/user_guides/components/button.png
+ === "Result"
+ [![Button]][button]
### Use as a control
-The [`Button`][vizro.models.Button] component is currently reserved to be used inside the main panel (right-side) of the dashboard.
-However, there might be use cases where one would like to place the `Button` inside the control panel (left-side) with the other controls.
+
+The [`Button`][vizro.models.Button] component is currently reserved to be used inside the main panel (right-side) of the dashboard. However, there might be use cases where one would like to place the `Button` inside the control panel (left-side) with the other controls.
In this case, follow the user-guide outlined for [creating custom components](custom-components.md) and manually add the `Button` as a valid type to the `controls` argument by running the following lines before your dashboard configurations:
@@ -748,3 +716,13 @@ vm.Page.add_type("controls", vm.Button)
# Add dashboard configurations below
...
```
+
+[button]: ../../assets/user_guides/components/button.png
+[buttontext]: ../../assets/user_guides/components/button_text.png
+[card]: ../../assets/user_guides/components/card.png
+[cardicon]: ../../assets/user_guides/components/card_icon.png
+[cardimagedefault]: ../../assets/user_guides/components/card_image_default.png
+[cardimagefloating]: ../../assets/user_guides/components/card_image_floating.png
+[cardimagestyled]: ../../assets/user_guides/components/card_image_styled.png
+[cardtext]: ../../assets/user_guides/components/card_text.png
+[navcard]: ../../assets/user_guides/components/nav_card.png
diff --git a/vizro-core/docs/pages/user-guides/components.md b/vizro-core/docs/pages/user-guides/components.md
index 106bf6a0b..45ea5a123 100755
--- a/vizro-core/docs/pages/user-guides/components.md
+++ b/vizro-core/docs/pages/user-guides/components.md
@@ -1,8 +1,6 @@
# Components
-The [`Page`][vizro.models.Page] model accepts the `components` argument, where you can enter any of the components
-listed below to fill your dashboard with visuals.
-
+The [`Page`][vizro.models.Page] model accepts the `components` argument, where you can enter any of the components listed below to fill your dashboard with visuals.
@@ -38,7 +36,6 @@ listed below to fill your dashboard with visuals.
[:octicons-arrow-right-24: View user guide](card-button.md)
-
- :octicons-table-16:{ .lg .middle } __Containers__
---
diff --git a/vizro-core/docs/pages/user-guides/container.md b/vizro-core/docs/pages/user-guides/container.md
index c7e327c5f..2f379709e 100755
--- a/vizro-core/docs/pages/user-guides/container.md
+++ b/vizro-core/docs/pages/user-guides/container.md
@@ -2,30 +2,22 @@
This guide shows you how to use containers to group your components into sections and subsections within the page.
-A [`Container`][vizro.models.Container] complements the idea of a [`Page`][vizro.models.Page], and the two models have almost identical arguments.
- [`Page.layout`](layouts.md) offers a way to structure the overall layout of the page, and a `Container` enables more granular control within a specific section of that page.
+A [`Container`][vizro.models.Container] complements the idea of a [`Page`][vizro.models.Page], and the two models have almost identical arguments. [`Page.layout`](layouts.md) offers a way to structure the overall layout of the page, and a `Container` enables more granular control within a specific section of that page.
-While there is currently no clear difference in rendering, extra functionality will be added to the `Container` soon (including controls specific to that container),
-enhancing the ability to manage related components.
+While there is currently no clear difference in rendering, extra functionality will be added to the `Container` soon (including controls specific to that container), enhancing the ability to manage related components.
!!! note "Displaying multiple containers inside Tabs"
-
An alternative way to display multiple containers on one page is to place them inside [Tabs](tabs.md).
- [`Tabs`][vizro.models.Tabs] organize and separate groups of related content in a dashboard, letting users switch between different sections or views.
- They are a way of putting multiple containers into the same screen space, and letting the user switch between them.
+ [`Tabs`][vizro.models.Tabs] organize and separate groups of related content in a dashboard, letting users switch between different sections or views. They are a way of putting multiple containers into the same screen space, and letting the user switch between them.
{ width="500" }
-
-
## When to use containers
-In general, any arbitrarily granular layout can already be achieved by [using `Page.layout`](layouts.md) alone and is our
-recommended approach if you want to arrange components on a page with consistent row and/or column spacing.
-`Page.layout` has a `grid` argument that sets the overall layout of the page.
-`Container.layout` also has a `grid` argument. This enables you to insert a further `grid` into a component's space on the page,
-enabling more granular control by breaking the overall page grid into subgrids.
+In general, any arbitrarily granular layout can already be achieved by [using `Page.layout`](layouts.md) alone and is our recommended approach if you want to arrange components on a page with consistent row and/or column spacing.
+
+`Page.layout` has a `grid` argument that sets the overall layout of the page. `Container.layout` also has a `grid` argument. This enables you to insert a further `grid` into a component's space on the page, enabling more granular control by breaking the overall page grid into subgrids.
Here are a few cases where you might want to use a `Container` instead of `Page.layout`:
@@ -34,14 +26,14 @@ Here are a few cases where you might want to use a `Container` instead of `Page.
- If you want different row and column spacing between subgrids
- If you want to apply controls to selected subgrids (will be supported soon)
-
## Basic containers
+
To add a [`Container`][vizro.models.Container] to your page, do the following:
1. Insert the `Container` into the `components` argument of the [`Page`][vizro.models.Page]
-2. Set a `title` for your `Container`
-3. Configure your `components`, [read the overview page for various options](components.md)
-4. (optional) Configure your `layout`, see [the guide on `Layout`](layouts.md)
+1. Set a `title` for your `Container`
+1. Configure your `components`, [read the overview page for various options](components.md)
+1. (optional) Configure your `layout`, see [the guide on `Layout`](layouts.md)
!!! example "Container"
=== "app.py"
@@ -105,7 +97,7 @@ To add a [`Container`][vizro.models.Container] to your page, do the following:
```
1. Note that the `Page.layout` argument is not specified here and will therefore defaults to `[[0], [1]]`, meaning the containers will be **vertically stacked** down the page in one column.
- 2. **Horizontally stack** the components side-by-side inside this `Container` in one row.
+ 1. **Horizontally stack** the components side-by-side inside this `Container` in one row.
=== "app.yaml"
```yaml
@@ -149,27 +141,20 @@ To add a [`Container`][vizro.models.Container] to your page, do the following:
title: Container II
title: Containers
```
- === "Result"
- [![Container]][Container]
- [Container]: ../../assets/user_guides/components/containers.png
+ === "Result"
+ [![Container]][container]
Note that an almost identical layout can also be achieved using solely the [`Page.layout`](layouts.md) by configuring the `Page.layout` as `vm.Layout(grid = [[0, 1], [2, 2]])`.
## Nested containers
-Containers can be nested, providing a hierarchical structure for organizing components.
-This nesting capability enables users to create more complex layouts and manage related components at any level of granularity.
+
+Containers can be nested, providing a hierarchical structure for organizing components. This nesting capability enables users to create more complex layouts and manage related components at any level of granularity.
To create nested containers, add a `Container` to the `components` argument of another `Container`.
```python title="Example"
-vm.Container(
- title="Parent Container",
- components=[
- vm.Container(
- title="Child Container",
- components=[vm.Button()]
- )
- ]
-)
+vm.Container(title="Parent Container", components=[vm.Container(title="Child Container", components=[vm.Button()])])
```
+
+[container]: ../../assets/user_guides/components/containers.png
diff --git a/vizro-core/docs/pages/user-guides/custom-actions.md b/vizro-core/docs/pages/user-guides/custom-actions.md
index e5fa3afd8..2fb66cd2c 100644
--- a/vizro-core/docs/pages/user-guides/custom-actions.md
+++ b/vizro-core/docs/pages/user-guides/custom-actions.md
@@ -1,17 +1,16 @@
# How to create custom actions
-This guide demonstrates the usage of custom actions, an idea that shares similarities with, but is not identical to [callbacks](https://dash.plotly.com/basic-callbacks) in `Dash`.
-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.
+This guide demonstrates the usage of custom actions, an idea that shares similarities with, but is not identical to [callbacks](https://dash.plotly.com/basic-callbacks) in `Dash`. 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.
+
## Simple custom action
Custom actions enable you to implement your own action function. Simply do the following:
1. define a function
-2. decorate it with the `@capture("action")` decorator
-3. add it as a `function` argument inside the [`Action`][vizro.models.Action] model
+1. decorate it with the `@capture("action")` decorator
+1. add it as a `function` argument inside the [`Action`][vizro.models.Action] model
The following example shows how to create a custom action that postpones execution of the next action in the chain for `t` seconds.
@@ -58,27 +57,24 @@ The following example shows how to create a custom action that postpones executi
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
- ```yaml
- # Custom actions are currently only possible via Python configuration
- ```
-
+ Custom actions are currently only possible via Python configuration.
+
## Interact with inputs and outputs
+
When a custom action needs to interact with the dashboard, it is possible to define `inputs` and `outputs` for the custom action.
-- `inputs` represents dashboard component properties whose values are passed to the custom action function as arguments.
-It is a list of strings in the format `"."` (for example, `"my_selector.value`").
-- `outputs` represents dashboard component properties corresponding to the custom action function return value(s).
-Similar to `inputs`, it is a list of strings in the format `"."` (for example, `"my_card.children"`).
+- `inputs` represents dashboard component properties whose values are passed to the custom action function as arguments. It is a list of strings in the format `"."` (for example, `"my_selector.value`").
+- `outputs` represents dashboard component properties corresponding to the custom action function return value(s). Similar to `inputs`, it is a list of strings in the format `"."` (for example, `"my_card.children"`).
### Example of `value` as input
-The following example shows a custom action that takes the `value` of the `vm.RadioItem` and returns it inside a
-[`Card`][vizro.models.Card] component.
-!!! example "Display `value` in Card"
+The following example shows a custom action that takes the `value` of the `vm.RadioItem` and returns it inside a [`Card`][vizro.models.Card] component.
+!!! example "Display `value` in Card"
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -113,23 +109,18 @@ The following example shows a custom action that takes the `value` of the `vm.Ra
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
- === "app.yaml"
- ```yaml
- # Custom actions are currently only possible via Python configuration
- ```
- === "Result"
- [![ValueAction]][ValueAction]
- [ValueAction]: ../../assets/user_guides/custom_actions/value_as_input.png
+ === "app.yaml"
+ Custom actions are currently only possible via Python configuration.
+ === "Result"
+ [![ValueAction]][valueaction]
### Example of `clickData` as input
-The following example shows how to create a custom action that shows the `clickData` of a chart in a
-[`Card`][vizro.models.Card] component. For further information on the structure and content of the `clickData`
-property, refer to the Dash documentation on [interactive visualizations](https://dash.plotly.com/interactive-graphing).
-!!! example "Display `clickData` in Card"
+The following example shows how to create a custom action that shows the `clickData` of a chart in a [`Card`][vizro.models.Card] component. For further information on the structure and content of the `clickData` property, refer to the Dash documentation on [interactive visualizations](https://dash.plotly.com/interactive-graphing).
+!!! example "Display `clickData` in Card"
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -173,21 +164,18 @@ property, refer to the Dash documentation on [interactive visualizations](https:
```
1. Just as for any Python function, the names of the arguments `show_species` and `points_data` are arbitrary and do not need to match on to the names of `inputs` in any particular way.
- 2. We _bind_ (set) the argument `show_species` to the value `True` in the initial specification of the `function` field. These are static values that are fixed when the dashboard is _built_.
- 3. The content of `inputs` will "fill in the gaps" by setting values for the remaining unbound arguments in `my_custom_action`. Here there is one such argument, named `points_data`. Values for these are bound _dynamically at runtime_ to reflect the live state of your dashboard.
+ 1. We _bind_ (set) the argument `show_species` to the value `True` in the initial specification of the `function` field. These are static values that are fixed when the dashboard is _built_.
+ 1. The content of `inputs` will "fill in the gaps" by setting values for the remaining unbound arguments in `my_custom_action`. Here there is one such argument, named `points_data`. Values for these are bound _dynamically at runtime_ to reflect the live state of your dashboard.
+
=== "app.yaml"
- ```yaml
- # Custom actions are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomAction]][CustomAction]
+ Custom actions are currently only possible via Python configuration.
- [CustomAction]: ../../assets/user_guides/custom_actions/clickdata_as_input.png
+ === "Result"
+ [![CustomAction]][customaction]
## Multiple return values
-The return value of the custom action function is propagated to the dashboard components that are defined in the `outputs` argument of the [`Action`][vizro.models.Action] model.
-If there is a single `output` defined then the function return value is directly assigned to the component property.
-If there are multiple `outputs` defined then the return value is iterated through and each part is assigned to each component property given in `outputs` in turn. This behavior is identical to Python's flexibility in managing multiple return values.
+
+The return value of the custom action function is propagated to the dashboard components that are defined in the `outputs` argument of the [`Action`][vizro.models.Action] model. If there is a single `output` defined then the function return value is directly assigned to the component property. If there are multiple `outputs` defined then the return value is iterated through and each part is assigned to each component property given in `outputs` in turn. This behavior is identical to Python's flexibility in managing multiple return values.
!!! example "Multiple return values"
=== "app.py"
@@ -246,17 +234,17 @@ If there are multiple `outputs` defined then the return value is iterated throug
```
1. `my_custom_action` returns two values (which will be in Python tuple).
- 2. These values are assigned to the `outputs` in the same order.
- === "app.yaml"
- ```yaml
- # Custom actions are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomAction2]][CustomAction2]
+ 1. These values are assigned to the `outputs` in the same order.
- [CustomAction2]: ../../assets/user_guides/custom_actions/custom_action_multiple_return_values.png
+ === "app.yaml"
+ Custom actions are currently only possible via Python configuration.
+ === "Result"
+ [![CustomAction2]][customaction2]
!!! warning
+ Note that users of this package are responsible for the content of any custom action function that they write. Take care to avoid leaking any sensitive information or exposing to any security threat during implementation. You should always [treat the content of user input as untrusted](https://community.plotly.com/t/writing-secure-dash-apps-community-thread/54619).
- Note that users of this package are responsible for the content of any custom action function that they write - especially with regard to leaking any sensitive information or exposing to any security threat during implementation. You should always [treat the content of user input as untrusted](https://community.plotly.com/t/writing-secure-dash-apps-community-thread/54619).
+[customaction]: ../../assets/user_guides/custom_actions/clickdata_as_input.png
+[customaction2]: ../../assets/user_guides/custom_actions/custom_action_multiple_return_values.png
+[valueaction]: ../../assets/user_guides/custom_actions/value_as_input.png
diff --git a/vizro-core/docs/pages/user-guides/custom-charts.md b/vizro-core/docs/pages/user-guides/custom-charts.md
index cb26614c8..1b77d0869 100644
--- a/vizro-core/docs/pages/user-guides/custom-charts.md
+++ b/vizro-core/docs/pages/user-guides/custom-charts.md
@@ -1,9 +1,9 @@
# 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 graphs](graph.md).
+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 graphs](graph.md).
## When to use a custom chart
+
In general, you should use the custom chart decorator `@capture("graph")` if your plotly chart needs any post-update calls or customization. For example:
- You want to use any of the post figure update calls by `plotly` such as `update_layout`, `update_xaxes`, `update_traces` (for more details, see the docs on [plotly's update calls](https://plotly.com/python/creating-and-updating-figures/#other-update-methods))
@@ -12,11 +12,10 @@ In general, you should use the custom chart decorator `@capture("graph")` if you
## Steps to create a custom chart
1. Define a function that returns a `go.Figure()`.
-2. Decorate it with `@capture("graph")`.
-3. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
-4. The visualization should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments
-will not react to dashboard controls such as [`Filter`](filters.md).
-5. Pass your function to the `figure` argument of the [`Graph`][vizro.models.Graph] model.
+1. Decorate it with `@capture("graph")`.
+1. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
+1. The visualization should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments will not react to dashboard controls such as [`Filter`](filters.md).
+1. Pass your function to the `figure` argument of the [`Graph`][vizro.models.Graph] model.
The minimal example below can be used as a base to build more sophisticated charts.
@@ -39,12 +38,10 @@ To alter the data in the `data_frame` argument, consider using a [Filter](filter
## Enhanced `plotly.express` chart with reference line
-The below examples shows a case where we enhance an existing `plotly.express` chart. We add a new argument (`hline`), that is used to draw a grey reference line at the height determined by the value of `hline`. The important thing to note is that we then
-add a `Parameter` that enables the dashboard user to interact with the argument, and hence move the line in this case. See the `Result` tab for an animation.
+The below examples shows a case where we enhance an existing `plotly.express` chart. We add a new argument (`hline`), that is used to draw a grey reference line at the height determined by the value of `hline`. The important thing to note is that we then add a `Parameter` that enables the dashboard user to interact with the argument, and hence move the line in this case. See the `Result` tab for an animation.
!!! example "Custom `plotly.express` scatter chart with a `Parameter`"
=== "app.py"
-
```{.python pycafe-link}
import vizro.models as vm
import vizro.plotly.express as px
@@ -86,17 +83,14 @@ add a `Parameter` that enables the dashboard user to interact with the argument,
Vizro().build(dashboard).run()
```
- 1. Note that arguments of the custom chart can be parametrized. Here we choose to parametrize the `hline` argument (see below).
- 2. Here we parametrize the `hline` argument, but any other argument can be parametrized as well. Since there is complete flexibility regarding what can be derived from such arguments, the dashboard user has a wide range of customization options.
- === "app.yaml"
- ```yaml
- # Custom charts are currently only possible via Python configuration
- ```
- === "Result"
- [![Graph2]][Graph2]
+ 1. Note that arguments of the custom chart can be parametrized. Here we choose to parametrize the `hline` argument (see below).
+ 1. Here we parametrize the `hline` argument, but any other argument can be parametrized as well. Since there is complete flexibility regarding what can be derived from such arguments, the dashboard user has a wide range of customization options.
- [Graph2]: ../../assets/user_guides/custom_charts/custom_chart_showcase_parameter.gif
+ === "app.yaml"
+ Custom charts are currently only possible via Python configuration.
+ === "Result"
+ [![Graph2]][graph2]
## New Waterfall chart based on `go.Figure()`
@@ -104,7 +98,6 @@ The below examples shows a more involved use-case. We create and style a waterfa
!!! example "Custom `go.Figure()` waterfall chart with a `Parameter`"
=== "app.py"
-
```{.python pycafe-link}
import pandas as pd
import plotly.graph_objects as go
@@ -162,10 +155,10 @@ The below examples shows a more involved use-case. We create and style a waterfa
```
=== "app.yaml"
- ```yaml
- # Custom charts are currently only possible via Python configuration
- ```
+ Custom charts are currently only possible via Python configuration.
+
=== "Result"
- [![Graph3]][Graph3]
+ [![Graph3]][graph3]
- [Graph3]: ../../assets/user_guides/custom_charts/custom_chart_waterfall.png
+[graph2]: ../../assets/user_guides/custom_charts/custom_chart_showcase_parameter.gif
+[graph3]: ../../assets/user_guides/custom_charts/custom_chart_waterfall.png
diff --git a/vizro-core/docs/pages/user-guides/custom-css.md b/vizro-core/docs/pages/user-guides/custom-css.md
index dd2d22275..d5bc5f7dc 100755
--- a/vizro-core/docs/pages/user-guides/custom-css.md
+++ b/vizro-core/docs/pages/user-guides/custom-css.md
@@ -1,25 +1,20 @@
# Customizing Vizro dashboard CSS
-Vizro is opinionated about visual formatting, and some elements, such as the layout of the navigation and controls,
-are fixed. You can customize some settings such as background colors, fonts, and other styles via CSS overrides.
+Vizro is opinionated about visual formatting, and some elements, such as the layout of the navigation and controls, are fixed. You can customize some settings such as background colors, fonts, and other styles via CSS overrides.
To make customizations, you need to:
1. **Add a CSS file to your `assets` folder**. Refer to our user guide on [adding static assets](assets.md#how-to-add-static-assets).
-2. **Identify the correct CSS selector** for the component you want to style.
-3. **Change the relevant CSS properties** in your CSS file.
-
-
+1. **Identify the correct CSS selector** for the component you want to style.
+1. **Change the relevant CSS properties** in your CSS file.
## Introduction to Vizro CSS
+
For a short introduction to CSS, we recommend reading this article: [Get Started with CSS in 5 Minutes](https://www.freecodecamp.org/news/get-started-with-css-in-5-minutes-e0804813fc3e/).
-For a more comprehensive tutorial, refer to the [W3Schools CSS tutorial](https://www.w3schools.com/css/default.asp).
-The entire tutorial is beneficial, but the section on [CSS selectors](https://www.w3schools.com/css/css_selectors.asp)
-will be particularly useful.
+For a more comprehensive tutorial, refer to the [W3Schools CSS tutorial](https://www.w3schools.com/css/default.asp). The entire tutorial is beneficial, but the section on [CSS selectors](https://www.w3schools.com/css/css_selectors.asp) will be particularly useful.
-In Vizro, the CSS file is read in as an external stylesheet. The most common way of applying any styling to
-Vizro is therefore through the use of CSS selectors:
+In Vizro, the CSS file is read in as an external stylesheet. The most common way of applying any styling to Vizro is therefore through the use of CSS selectors:
- **Element Selector**: Applies the style to all elements inside the Vizro app.
@@ -33,8 +28,7 @@ Vizro is therefore through the use of CSS selectors:
}
```
-- **Class selector:** Targets all elements with the given class for styling. All CSS classes must be preceded with a
-`.` symbol.
+- **Class selector:** Targets all elements with the given class for styling. All CSS classes must be preceded with a `.` symbol.
```
.card {
@@ -50,30 +44,25 @@ Vizro is therefore through the use of CSS selectors:
}
```
-
## Identify the correct CSS selector
Use Chrome DevTools or a similar tool (Web Inspector, Web Developer Tools, etc.) to inspect the HTML document in your browser.
-1. **Open DevTools:** In Google Chrome, right-click on the app and select "Inspect" from the context menu. This opens the
-HTML document of your Vizro app.
+1. **Open DevTools:** In Google Chrome, right-click on the app and select "Inspect" from the context menu. This opens the HTML document of your Vizro app.
-
-2. **Select an element:** Suppose you want to change the background color of your cards. Click the
-"Select an element in the page to inspect it" icon in the top left corner of the inspect panel.
+1. **Select an element:** Suppose you want to change the background color of your cards. Click the "Select an element in the page to inspect it" icon in the top left corner of the inspect panel.
-3. **Find the HTML Block:** Hover over the component you want to style. The corresponding HTML block will be
-highlighted in the HTML document.
+1. **Find the HTML Block:** Hover over the component you want to style. The corresponding HTML block will be highlighted in the HTML document.
Notice that the selected HTML block corresponds to the container of the card and has a CSS class, here it is `card`.
-4. **Apply CSS:** Use this CSS class to style the card component. In your CSS file, you can write:
+1. **Apply CSS:** Use this CSS class to style the card component. In your CSS file, you can write:
```
.card {
@@ -83,25 +72,25 @@ highlighted in the HTML document.
This changes the background color for any HTML element with the `card` class.
-**Tip:** You can also test your CSS live by editing the CSS attributes in the "Elements" panel.
-For example, temporarily add `background: blue;`. Note that this change will be lost upon reloading the page.
+**Tip:** You can also test your CSS live by editing the CSS attributes in the "Elements" panel. For example, temporarily add `background: blue;`. Note that this change will be lost upon reloading the page.
-
## CSS overwrites
### Overwrite CSS globally
-To overwrite any global CSS property, you need to target the element selector and place your CSS file with the
-overwrites in the `assets` folder.
+
+To overwrite any global CSS property, you need to target the element selector and place your CSS file with the overwrites in the `assets` folder.
!!! example "Overwrite CSS globally"
=== "my_css_file.css"
- ```css
- h1, h2 {
- color: hotpink;
- }
- ```
+ ```css
+ h1,
+ h2 {
+ color: hotpink;
+ }
+ ```
+
=== "app.py"
```py
import os
@@ -134,44 +123,41 @@ overwrites in the `assets` folder.
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # This is an tag
+ - components:
+ - text: |
+ # This is an tag
- ## This is an tag
+ ## This is an tag
- ###### This is an tag
- type: card
- title: Changing the header color
+ ###### This is an tag
+ type: card
+ title: Changing the header color
```
- === "Result"
- [![AssetsCSS]][AssetsCSS]
-
- [AssetsCSS]: ../../assets/user_guides/assets/css_change.png
+ === "Result"
+ [![AssetsCSS]][assetscss]
### Overwrite CSS for selected pages
-To style components for a specific page, use the page's `id` in the CSS selectors. By default, this is the
-[same as the page `title`](pages.md), but such a value might not be a valid CSS identifier.
-A suitable `id` must be unique across all models in the dashboard and should contain only alphanumeric
-characters, hyphens (`-`) and underscores (`_`). In particular, note that spaces are _not_ allowed.
+To style components for a specific page, use the page's `id` in the CSS selectors. By default, this is the [same as the page `title`](pages.md), but such a value might not be a valid CSS identifier.
+
+A suitable `id` must be unique across all models in the dashboard and should contain only alphanumeric characters, hyphens (`-`) and underscores (`_`). In particular, note that spaces are _not_ allowed.
Suppose you want to hide the page title on one page only. Here's how you can achieve this:
1. Give a valid `id` to the `Page`, for example `Page(id="page-with-hidden-title", title="Page with hidden title", ...)`.
-2. Identify the CSS class or CSS `id` you need to target. To hide the page title, you need to hide the parent container with the id `right-header`.
-3. Use the `id` to hide the content.
-4. Add your custom css file to the `assets` folder.
-
+1. Identify the CSS class or CSS `id` you need to target. To hide the page title, you need to hide the parent container with the id `right-header`.
+1. Use the `id` to hide the content.
+1. Add your custom css file to the `assets` folder.
!!! example "Hide page title on selected pages"
=== "my_css_file.css"
- ```css
- #page-with-hidden-title #right-header {
- display: none;
- }
- ```
+ ```css
+ #page-with-hidden-title #right-header {
+ display: none;
+ }
+ ```
+
=== "app.py"
```py
import vizro.models as vm
@@ -199,25 +185,24 @@ Suppose you want to hide the page title on one page only. Here's how you can ach
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Placeholder
- type: card
- title: Page with hidden title
- id: page-with-hidden-title
- - components:
- - text: |
- # Placeholder
- type: card
- title: Page with shown title
+ - components:
+ - text: |
+ # Placeholder
+ type: card
+ title: Page with hidden title
+ id: page-with-hidden-title
+ - components:
+ - text: |
+ # Placeholder
+ type: card
+ title: Page with shown title
```
- === "Result"
- [![PageTitle]][PageTitle]
-
- [PageTitle]: ../../assets/user_guides/assets/css_page_title.png
+ === "Result"
+ [![PageTitle]][pagetitle]
### Overwrite CSS for selected components
+
To adjust CSS properties for specific components, such as altering the appearance of a selected [`Card`][vizro.models.Card] rather than all Cards, you need to supply an `id` to the component you want to style.
Let's say we want to change the `background-color` and `color` of a specific `Card`.
@@ -225,41 +210,43 @@ Let's say we want to change the `background-color` and `color` of a specific `Ca
Here's how you can do it:
1. Assign a unique `id` to the relevant `Card`, for example: `Card(id="custom-card", ...)`
-2. Run your dashboard and open it in your browser
-3. View the HTML document to find the appropriate CSS class or element you need to target, as explained in the section
-on [identifying the correct CSS selector](#identify-the-correct-css-selector).
+1. Run your dashboard and open it in your browser
+1. View the HTML document to find the appropriate CSS class or element you need to target, as explained in the section on [identifying the correct CSS selector](#identify-the-correct-css-selector).
-It's essential to understand the relationship between the targeted CSS class or element and the component assigned
-`id`, for example:
+It's essential to understand the relationship between the targeted CSS class or element and the component assigned `id`, for example:
-```html title="HTML structure of a `Card`"
+
+```html title="HTML structure of a card"
-
- Lorem ipsum dolor sit amet consectetur adipisicing elit.
-
+
+
+ Lorem ipsum dolor sit amet consectetur adipisicing elit.
+
+
```
-
-* **Main element with `id`:** There is a `` with our `id="custom-card"`.
-* **Parent element:** That `` is wrapped inside a parent `` with the class name `"card"`. This is the element we need to target to change the background color.
-* **Child element:** The card text is wrapped inside a `` that is a child of the `
` with our `id`. This is the element we need to target to change the font color.
+
+- **Main element with `id`:** There is a `` with our `id="custom-card"`.
+- **Parent element:** That `` is wrapped inside a parent `` with the class name `"card"`. This is the element we need to target to change the background color.
+- **Child element:** The card text is wrapped inside a `` that is a child of the `
` with our `id`. This is the element we need to target to change the font color.
!!! example "Customizing CSS properties in selective components"
=== "my_css_file.css"
- ```css
- /* Apply styling to parent */
- .card:has(#custom-card) {
- background-color: white;
- }
+ ```css
+ /* Apply styling to parent */
+ .card:has(#custom-card) {
+ background-color: white;
+ }
+
+ /* Apply styling to child */
+ #custom-card p {
+ color: black;
+ }
+ ```
- /* Apply styling to child */
- #custom-card p {
- color: black;
- }
- ```
=== "app.py"
```py
import vizro.models as vm
@@ -285,77 +272,65 @@ It's essential to understand the relationship between the targeted CSS class or
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- Lorem ipsum dolor sit amet consectetur adipisicing elit.
- type: card
- id: custom-card
- - text: |
- Lorem ipsum dolor sit amet consectetur adipisicing elit.
- type: card
- title: Changing the card color
+ - components:
+ - text: |
+ Lorem ipsum dolor sit amet consectetur adipisicing elit.
+ type: card
+ id: custom-card
+ - text: |
+ Lorem ipsum dolor sit amet consectetur adipisicing elit.
+ type: card
+ title: Changing the card color
```
- === "Result"
- [![CardCSS]][CardCSS]
-
- [CardCSS]: ../../assets/user_guides/assets/css_change_card.png
+ === "Result"
+ [![CardCSS]][cardcss]
!!! note "Relationship between model ID and CSS ID"
+ Some Vizro components produce a single HTML element with an ID that matches the model ID, allowing you to target it directly using the CSS #id selector. Other components generate multiple HTML elements. Within these, the "core" element will have an ID matching the model ID, while non-core elements may have IDs that are variations of it, such as `{model-id}-title`.
- Some Vizro components produce a single HTML element with an ID that matches the model ID, allowing you to target it
- directly using the CSS #id selector. Other components generate multiple HTML elements. Within these, the "core"
- element will have an ID matching the model ID, while non-core elements may have IDs that are variations of it,
- such as `{model-id}-title`.
-
- In all instances, you can determine the correct selector by using Chrome DevTools or a similar tool after setting the
- appropriate model ID.
-
+ In all instances, you can determine the correct selector by using Chrome DevTools or a similar tool after setting the appropriate model ID.
## Common examples
### Make your CSS responsive to theme switches with variables
-To ensure your CSS adapts to theme changes, we recommend using CSS variables (`var`) whenever possible. For a
-comprehensive list of available variable names, refer to the
-[Bootstrap documentation](https://getbootstrap.com/docs/5.3/customize/css-variables/). Note that our
-Bootstrap stylesheet is still under development, so not all Bootstrap variables are currently available.
-Additionally, you can define your own CSS variables, as demonstrated in the example on
-[changing the container background color](#change-the-styling-of-a-container).
+
+To ensure your CSS adapts to theme changes, we recommend using CSS variables (`var`) whenever possible. For a comprehensive list of available variable names, refer to the [Bootstrap documentation](https://getbootstrap.com/docs/5.3/customize/css-variables/). Note that our Bootstrap stylesheet is still under development, so not all Bootstrap variables are currently available. Additionally, you can define your own CSS variables, as demonstrated in the example on [changing the container background color](#change-the-styling-of-a-container).
### Turn off page title
+
See the example above on [hiding the page title on selected pages](#overwrite-css-for-selected-pages).
### Change the background color of a card
+
See the example above on [customizing CSS properties in selective components](#overwrite-css-for-selected-components).
### Change the global font
+
The default fonts for a Vizro app are `Inter, sans-serif, Arial, serif`.
If you need to change the global font, perhaps to adhere to branding guidelines, follow these steps:
1. Download the desired font from a font provider such as [Google Fonts](https://fonts.google.com/).
-2. Place the font file (`.ttf`, `woff2`, etc.) into your `assets` folder. Here’s an example of what the assets folder might look like:
- 
+1. Place the font file (`.ttf`, `woff2`, etc.) into your `assets` folder. Here’s an example of what the assets folder might look like:
-3. Add the font to your CSS file using the `@font-face` rule and apply the font globally to your Vizro app, making sure
-to specify fallback fonts. Add the following to your `custom.css` file:
+ 
+1. Add the font to your CSS file using the `@font-face` rule and apply the font globally to your Vizro app, making sure to specify fallback fonts. Add the following to your `custom.css` file:
```css
@font-face {
- font-family: PlayfairDisplay;
- src: url("PlayfairDisplay-VariableFont_wght.ttf") format("truetype");
+ font-family: PlayfairDisplay;
+ src: url("PlayfairDisplay-VariableFont_wght.ttf") format("truetype");
}
* {
- font-family: PlayfairDisplay, Inter, sans-serif, Arial, serif;
+ font-family: PlayfairDisplay, Inter, sans-serif, Arial, serif;
}
```
-
-4. Note that the modification above applies solely to the dashboard font. To also change the font within the
-Plotly charts, you must specify this at the beginning of your `app.py` file:
+1. Note that the modification above applies solely to the dashboard font. To also change the font within the Plotly charts, you must specify this at the beginning of your `app.py` file:
```python
import plotly.io as pio
@@ -365,44 +340,42 @@ Plotly charts, you must specify this at the beginning of your `app.py` file:
```
### Reposition the logo
-By default, the logo appears in the top left corner of the dashboard. You can move it further to the left or right by
-adjusting the `padding` of the `#page-header` element. Here is an example of how to achieve this:
+
+By default, the logo appears in the top left corner of the dashboard. You can move it further to the left or right by adjusting the `padding` of the `#page-header` element. Here is an example of how to achieve this:
```css
#page-header {
- padding-left: 8px;
+ padding-left: 8px;
}
```
-
### Change the styling of a container
-If you want to make the subsections of your dashboard stand out more, you can do this by placing your components
-inside a [Container](container.md) and changing the container's styling, for example, background color, borders, padding, etc.
-To do this, you need to change the container's CSS class. Using the DevTool, as explained in the section on
-[identifying the correct CSS selector](#identify-the-correct-css-selector), you'll find that the CSS class for the
-`Container` is `page-component-container`. You can then use this class to set a new `background-color` and `padding`.
+If you want to make the subsections of your dashboard stand out more, you can do this by placing your components inside a [Container](container.md) and changing the container's styling, for example, background color, borders, padding, etc.
+
+To do this, you need to change the container's CSS class. Using the DevTool, as explained in the section on [identifying the correct CSS selector](#identify-the-correct-css-selector), you'll find that the CSS class for the `Container` is `page-component-container`. You can then use this class to set a new `background-color` and `padding`.
!!! example "Style a container"
=== "custom.css"
- ```css
- /* Assign a variable to the dark and light theme */
- [data-bs-theme="dark"] {
- --container-bg-color: #232632;
- }
-
- [data-bs-theme="light"] {
- --container-bg-color: #F5F6F6;
- }
+ ```css
+ /* Assign a variable to the dark and light theme */
+ [data-bs-theme="dark"] {
+ --container-bg-color: #232632;
+ }
+
+ [data-bs-theme="light"] {
+ --container-bg-color: #F5F6F6;
+ }
+
+ /* Use the custom variable var(--container-bg-color) */
+ .page-component-container {
+ background: var(--container-bg-color);
+ padding: 12px;
+ }
+ ```
- /* Use the custom variable var(--container-bg-color) */
- .page-component-container {
- background: var(--container-bg-color);
- padding: 12px;
- }
- ```
=== "app.py"
```py
import vizro.models as vm
@@ -437,12 +410,12 @@ To do this, you need to change the container's CSS class. Using the DevTool, as
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - title: "Page with subsections"
+ - title: Page with subsections
layout:
grid: [[0, 1]]
components:
- type: container
- title: "Container I"
+ title: Container I
components:
- type: graph
figure:
@@ -452,7 +425,7 @@ To do this, you need to change the container's CSS class. Using the DevTool, as
y: sepal_length
color: species
- type: container
- title: "Container II"
+ title: Container II
components:
- type: graph
figure:
@@ -462,13 +435,11 @@ To do this, you need to change the container's CSS class. Using the DevTool, as
y: sepal_length
color: species
```
- === "Result"
- [![StyleContainer]][StyleContainer]
- [StyleContainer]: ../../assets/user_guides/custom_css/style-container.png
+ === "Result"
+ [![StyleContainer]][stylecontainer]
-You will notice that the background colors of the charts are different. To align it with the colors of the container,
-you can make the charts' background transparent.
+You will notice that the background colors of the charts are different. To align it with the colors of the container, you can make the charts' background transparent.
To make the background of all charts transparent:
@@ -492,3 +463,8 @@ def custom_chart(data_frame):
```
+
+[assetscss]: ../../assets/user_guides/assets/css_change.png
+[cardcss]: ../../assets/user_guides/assets/css_change_card.png
+[pagetitle]: ../../assets/user_guides/assets/css_page_title.png
+[stylecontainer]: ../../assets/user_guides/custom_css/style-container.png
diff --git a/vizro-core/docs/pages/user-guides/custom-figures.md b/vizro-core/docs/pages/user-guides/custom-figures.md
index f135127be..3a178932f 100644
--- a/vizro-core/docs/pages/user-guides/custom-figures.md
+++ b/vizro-core/docs/pages/user-guides/custom-figures.md
@@ -1,41 +1,36 @@
# How to create custom figures
-This guide explains how to create custom figures, which is useful when you need a component that reacts to
-[filter](filters.md) and [parameter](parameters.md) controls.
+This guide explains how to create custom figures, which is 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).
## When to use a custom figure
-As described in the flowchart detailing [when to use `Figure`](figure.md), custom figures should be used if
-**both** of the following conditions are met:
+
+As described in the flowchart detailing [when to use `Figure`](figure.md), custom figures should be used if **both** of the following conditions are met:
- You need a figure that doesn't fit into the existing pre-defined components ([`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid]).
- You need a figure that isn't available in our pre-defined figure functions [`vizro.figures`](../API-reference/figure-callables.md).
## Steps to create a custom figure
-1. Define a function that returns a [Dash component](https://dash.plotly.com/#open-source-component-libraries).
-This can, but does not need to, be based on code in our pre-defined figure functions in [`vizro.figures`](../API-reference/figure-callables.md).
-2. Decorate it with `@capture("figure")`.
-3. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
-4. The figure should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments
-will not react to dashboard controls such as [`Filter`](filters.md).
-5. Pass your function to the `figure` argument of the [`Figure`][vizro.models.Figure] model.
+1. Define a function that returns a [Dash component](https://dash.plotly.com/#open-source-component-libraries). This can, but does not need to, be based on code in our pre-defined figure functions in [`vizro.figures`](../API-reference/figure-callables.md).
+1. Decorate it with `@capture("figure")`.
+1. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
+1. The figure should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments will not react to dashboard controls such as [`Filter`](filters.md).
+1. Pass your function to the `figure` argument of the [`Figure`][vizro.models.Figure] model.
The following examples can be used as a base to build more sophisticated figures.
## Examples of custom figures
### Custom KPI card
-To change the design or content of our existing KPI (key performance indicator) cards from
-[`vizro.figures`](../API-reference/figure-callables.md), you can do so by following the steps described above.
-For instance, to make a KPI card with the icon positioned on the right side of the title instead of the left,
-copy and paste the [source code of `kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card) and
-adjust the return statement of the function.
+To change the design or content of our existing KPI (key performance indicator) cards from [`vizro.figures`](../API-reference/figure-callables.md), you can do so by following the steps described above.
+
+For instance, to make a KPI card with the icon positioned on the right side of the title instead of the left, copy and paste the [source code of `kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card) and adjust the return statement of the function.
+
!!! example "Custom KPI card"
=== "app.py"
```{.python pycafe-link}
@@ -107,29 +102,26 @@ adjust the return statement of the function.
```
1. Here we decorate our custom figure function with the `@capture("figure")` decorator.
- 2. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
- 3. We adjust the return statement to include the icon on the right side of the title. This is achieved by swapping the order of the `html.H2` and `html.P` compared to the original `kpi_card`.
- 4. This creates a [`layout`](layouts.md) with four rows and columns. The KPI cards are positioned in the first two cells, while the remaining cells are empty.
- 5. For more information, refer to the API reference for the [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card).
- 6. Our custom figure function `custom_kpi_card` now needs to be passed on to the `vm.Figure`.
+ 1. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
+ 1. We adjust the return statement to include the icon on the right side of the title. This is achieved by swapping the order of the `html.H2` and `html.P` compared to the original `kpi_card`.
+ 1. This creates a [`layout`](layouts.md) with four rows and columns. The KPI cards are positioned in the first two cells, while the remaining cells are empty.
+ 1. For more information, refer to the API reference for the [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card).
+ 1. Our custom figure function `custom_kpi_card` now needs to be passed on to the `vm.Figure`.
=== "app.yaml"
- ```yaml
- # Custom figures are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomKPI]][CustomKPI]
+ Custom figures are currently only possible via Python configuration.
- [CustomKPI]: ../../assets/user_guides/figure/custom_kpi.png
+ === "Result"
+ [![CustomKPI]][customkpi]
### Dynamic HTML header
-You can create a custom figure for any [Dash component](https://dash.plotly.com/#open-source-component-libraries).
-Below is an example of a custom figure that returns a `html.H2` component that dynamically updates based on the selected
-name from a filter.
+
+You can create a custom figure for any [Dash component](https://dash.plotly.com/#open-source-component-libraries). Below is an example of a custom figure that returns a `html.H2` component that dynamically updates based on the selected name from a filter.
+
!!! example "Dynamic HTML header"
=== "app.py"
```{.python pycafe-link}
@@ -159,27 +151,24 @@ name from a filter.
```
1. Here we decorate our custom figure function with the `@capture("figure")` decorator.
- 2. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
- 3. We return a `html.H2` component that dynamically updates based on the selected name from the filter.
- 4. Our custom figure function `dynamic_html_header` now needs to be passed on to the `vm.Figure`.
+ 1. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
+ 1. We return a `html.H2` component that dynamically updates based on the selected name from the filter.
+ 1. Our custom figure function `dynamic_html_header` now needs to be passed on to the `vm.Figure`.
=== "app.yaml"
- ```yaml
- # Custom figures are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomHTML]][CustomHTML]
+ Custom figures are currently only possible via Python configuration.
- [CustomHTML]: ../../assets/user_guides/figure/custom_html.png
+ === "Result"
+ [![CustomHTML]][customhtml]
-
### Dynamic number of cards
-The example below shows how to create multiple cards created from a `pandas.DataFrame` where the
-number of cards displayed dynamically adjusts based on a `vm.Parameter`.
+
+The example below shows how to create multiple cards created from a `pandas.DataFrame` where the number of cards displayed dynamically adjusts based on a `vm.Parameter`.
+
!!! example "Dynamic number of cards"
=== "app.py"
```py
@@ -239,40 +228,39 @@ number of cards displayed dynamically adjusts based on a `vm.Parameter`.
```
1. Here we decorate our custom figure function with the `@capture("figure")` decorator.
- 2. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
- 3. Our decorated figure function `multiple_cards` now needs to be passed on to the `vm.Figure`.
- 4. We add a [`vm.Parameter`](parameters.md) to dynamically adjust the number of cards displayed.
- The parameter targets the `n_rows` argument of the `multiple_cards` function, determining the number of rows
- taken from the data.
+ 1. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
+ 1. Our decorated figure function `multiple_cards` now needs to be passed on to the `vm.Figure`.
+ 1. We add a [`vm.Parameter`](parameters.md) to dynamically adjust the number of cards displayed. The parameter targets the `n_rows` argument of the `multiple_cards` function, determining the number of rows taken from the data.
Run and edit this code in PyCafe
=== "styling.css"
```css
.multiple-cards-container {
- display: flex;
- flex-wrap: wrap;
- gap: 12px;
+ display: flex;
+ flex-wrap: wrap;
+ gap: 12px;
}
.figure-container {
- height: unset;
- width: unset;
+ height: unset;
+ width: unset;
}
.figure-container .card {
- height: 210px;
- width: 240px;
+ height: 210px;
+ width: 240px;
}
```
- === "app.yaml"
- ```yaml
- # Custom figures are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomFigure]][CustomFigure]
- [CustomFigure]: ../../assets/user_guides/figure/custom_multiple_cards.png
+ === "app.yaml"
+ Custom figures are currently only possible via Python configuration.
+ === "Result"
+ [![CustomFigure]][customfigure]
+
+[customfigure]: ../../assets/user_guides/figure/custom_multiple_cards.png
+[customhtml]: ../../assets/user_guides/figure/custom_html.png
+[customkpi]: ../../assets/user_guides/figure/custom_kpi.png
diff --git a/vizro-core/docs/pages/user-guides/custom-tables.md b/vizro-core/docs/pages/user-guides/custom-tables.md
index e990cfbb0..42748820b 100644
--- a/vizro-core/docs/pages/user-guides/custom-tables.md
+++ b/vizro-core/docs/pages/user-guides/custom-tables.md
@@ -1,21 +1,18 @@
# How to create custom Dash AG Grids and Dash DataTables
-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.
+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.
-The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] model accept the `figure` argument, where you can enter
-_any_ [`dash_ag_grid`][vizro.tables.dash_ag_grid] or [`dash_data_table`][vizro.tables.dash_data_table] chart as explained in the [user guide on tables](table.md).
+The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] model accept the `figure` argument, where you can enter _any_ [`dash_ag_grid`][vizro.tables.dash_ag_grid] or [`dash_data_table`][vizro.tables.dash_data_table] chart as explained in the [user guide on tables](table.md).
One reason could be that you want to create a table/grid that requires computations that can be controlled by parameters (see the example below).
### Steps to create a custom table
1. Define a function that returns a `dash_ag_grid.AgGrid` or `dash_table.DataTable` object.
-2. Decorate it with `@capture("ag_grid")` or `@capture("table")`.
-3. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
-4. The table should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments
-will not react to dashboard controls such as [`Filter`](filters.md).
-5. Pass your function to the `figure` argument of the [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid] model.
+1. Decorate it with `@capture("ag_grid")` or `@capture("table")`.
+1. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
+1. The table should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments will not react to dashboard controls such as [`Filter`](filters.md).
+1. Pass your function to the `figure` argument of the [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid] model.
The following examples show a possible version of a custom table. In this case the argument `chosen_columns` was added, which you can control with a parameter:
@@ -70,14 +67,12 @@ The following examples show a possible version of a custom table. In this case t
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
- ```yaml
- # Custom tables are currently only possible via Python configuration
- ```
- === "Result"
- [![Table3]][Table3]
+ Custom tables are currently only possible via Python configuration.
- [Table3]: ../../assets/user_guides/table/custom_table.png
+ === "Result"
+ [![Table3]][table3]
??? example "Custom Dash AgGrid"
=== "app.py"
@@ -136,11 +131,12 @@ The following examples show a possible version of a custom table. In this case t
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
- ```yaml
- # Custom Ag Grids are currently only possible via Python configuration
- ```
+ Custom Ag Grids are currently only possible via Python configuration.
+
=== "Result"
- [![GridCustom]][GridCustom]
+ [![GridCustom]][gridcustom]
- [GridCustom]: ../../assets/user_guides/table/custom_grid.png
+[gridcustom]: ../../assets/user_guides/table/custom_grid.png
+[table3]: ../../assets/user_guides/table/custom_table.png
diff --git a/vizro-core/docs/pages/user-guides/dashboard.md b/vizro-core/docs/pages/user-guides/dashboard.md
index 0b37e03fa..244f65256 100644
--- a/vizro-core/docs/pages/user-guides/dashboard.md
+++ b/vizro-core/docs/pages/user-guides/dashboard.md
@@ -1,16 +1,15 @@
# How to create a dashboard
-This guide shows you how to configure and call a [`Dashboard`][vizro.models.Dashboard] using either
-pydantic models, Python dictionaries, YAML, or JSON.
+
+This guide shows you how to configure and call a [`Dashboard`][vizro.models.Dashboard] using either pydantic models, Python dictionaries, YAML, or JSON.
To create a dashboard:
1. Choose one of the possible configuration syntaxes
-2. Create your `pages`, see our [guide on Pages](pages.md)
-3. (optional) Choose a `theme`, see our [guide on Themes](themes.md)
-4. (optional) Customize your `navigation`, see our [guide on Navigation](navigation.md)
-5. (optional) Set a `title` for your dashboard
-6. Add your `dashboard` to the `build` call of Vizro
-
+1. Create your `pages`, see our [guide on Pages](pages.md)
+1. (optional) Choose a `theme`, see our [guide on Themes](themes.md)
+1. (optional) Customize your `navigation`, see our [guide on Navigation](navigation.md)
+1. (optional) Set a `title` for your dashboard
+1. Add your `dashboard` to the `build` call of Vizro
## Use dashboard configuration options
@@ -37,6 +36,7 @@ To create a dashboard:
Vizro().build(dashboard).run()
```
+
=== "app.py - Python dict"
```py
import vizro.plotly.express as px
@@ -77,6 +77,7 @@ To create a dashboard:
Vizro().build(dashboard).run()
```
+
=== "dashboard.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -101,50 +102,49 @@ To create a dashboard:
type: filter
title: My first dashboard
```
+
=== "dashboard.json"
```json
{
- "pages": [
+ "pages": [
+ {
+ "components": [
+ {
+ "figure": {
+ "_target_": "scatter",
+ "color": "species",
+ "data_frame": "iris",
+ "x": "sepal_length",
+ "y": "petal_width"
+ },
+ "type": "graph"
+ },
{
- "components": [
- {
- "figure": {
- "_target_": "scatter",
- "color": "species",
- "data_frame": "iris",
- "x": "sepal_length",
- "y": "petal_width"
- },
- "type": "graph"
- },
- {
- "figure": {
- "_target_": "histogram",
- "color": "species",
- "data_frame": "iris",
- "x": "sepal_width",
- },
- "type": "graph"
- }
- ],
- "controls": [
- {
- "column": "species",
- "type": "filter"
- }
- ],
- "title": "My first dashboard"
+ "figure": {
+ "_target_": "histogram",
+ "color": "species",
+ "data_frame": "iris",
+ "x": "sepal_width"
+ },
+ "type": "graph"
}
- ]
+ ],
+ "controls": [
+ {
+ "column": "species",
+ "type": "filter"
+ }
+ ],
+ "title": "My first dashboard"
+ }
+ ]
}
```
- === "Result"
- [![Dashboard]][Dashboard]
- [Dashboard]: ../../assets/user_guides/dashboard/dashboard.png
+ === "Result"
+ [![Dashboard]][dashboard]
!!! note "Extra `.py` files for `yaml` and `json` required"
-
Note that in the `yaml` and `json` example an extra `.py` is required to register the data and parse the yaml/json configuration.
=== "app.py for yaml"
@@ -164,6 +164,7 @@ To create a dashboard:
Vizro().build(dashboard).run()
```
+
=== "app.py for json"
```py
import json
@@ -187,7 +188,6 @@ After running the dashboard, you can access the dashboard via `localhost:8050`.
If supplied, the `title` of the [`Dashboard`][vizro.models.Dashboard] displays a heading at the top of every page.
-
## Add a dashboard logo
Vizro will [automatically incorporate the dashboard logo](assets.md/#add-a-logo-image) in the top-left corner of each page if an image named `logo.` is present within the assets folder.
@@ -196,11 +196,10 @@ Vizro will [automatically incorporate the dashboard logo](assets.md/#add-a-logo-
## Browser title
-The [website icon](assets.md/#change-the-favicon), Dashboard `title` (if supplied) and [Page `title`][vizro.models.Page] are displayed in the browser's
-title bar. For example, if your Dashboard `title` is "Vizro Demo" and the Page `title` is "Homepage", then the title in the browser tab will be "Vizro Demo: Homepage".
+The [website icon](assets.md/#change-the-favicon), Dashboard `title` (if supplied) and [Page `title`][vizro.models.Page] are displayed in the browser's title bar. For example, if your Dashboard `title` is "Vizro Demo" and the Page `title` is "Homepage", then the title in the browser tab will be "Vizro Demo: Homepage".
## Meta tags for social media
-Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat
-clients. The preview includes the `URL`, `title`, plus an [image](assets.md/#include-a-meta-tags-image) and
-[Page `description`][vizro.models.Page] (if supplied). To see an example, try sharing an example from the [Vizro examples gallery](https://vizro.mckinsey.com/).
+Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat clients. The preview includes the `URL`, `title`, plus an [image](assets.md/#include-a-meta-tags-image) and [Page `description`][vizro.models.Page] (if supplied). To see an example, try sharing an example from the [Vizro examples gallery](https://vizro.mckinsey.com/).
+
+[dashboard]: ../../assets/user_guides/dashboard/dashboard.png
diff --git a/vizro-core/docs/pages/user-guides/data.md b/vizro-core/docs/pages/user-guides/data.md
index 51bf84b97..d19b8aafb 100644
--- a/vizro-core/docs/pages/user-guides/data.md
+++ b/vizro-core/docs/pages/user-guides/data.md
@@ -2,11 +2,12 @@
Vizro supports two different types of data:
-* [Static data](#static-data): pandas DataFrame. This is the simplest method and best to use if you do not need the more advanced functionality of dynamic data.
-* [Dynamic data](#dynamic-data): function that returns a pandas DataFrame. This is a bit more complex to understand but has more advanced functionality such as the ability to refresh data while the dashboard is running.
+- [Static data](#static-data): pandas DataFrame. This is the simplest method and best to use if you do not need the more advanced functionality of dynamic data.
+- [Dynamic data](#dynamic-data): function that returns a pandas DataFrame. This is a bit more complex to understand but has more advanced functionality such as the ability to refresh data while the dashboard is running.
The following flowchart shows what you need to consider when choosing how to set up your data.
-``` mermaid
+
+```mermaid
graph TD
refresh["`Do you need your data to refresh while the dashboard is running?`"]
specification["`Do you need to specify your dashboard through a configuration language like YAML?`"]
@@ -27,11 +28,10 @@ graph TD
```
??? note "Static vs. dynamic data comparison"
-
This table gives a full comparison between static and dynamic data. Do not worry if you do not yet understand everything in it; it will become clearer after reading more about [static data](#static-data) and [dynamic data](#dynamic-data)!
| | Static | Dynamic |
- |---------------------------------------------------------------|------------------|------------------------------------------|
+ | ------------------------------------------------------------- | ---------------- | ---------------------------------------- |
| Required Python type | pandas DataFrame | Function that returns a pandas DataFrame |
| Can be supplied directly in `data_frame` argument of `figure` | Yes | No |
| Can be referenced by name after adding to data manager | Yes | Yes |
@@ -73,14 +73,13 @@ The below example uses the Iris data saved to a file `iris.csv` in the same dire
```
1. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
- === "Result"
- [![DataBasic]][DataBasic]
- [DataBasic]: ../../assets/user_guides/data/data_pandas_dataframe.png
+ === "Result"
+ [![DataBasic]][databasic]
The [`Graph`][vizro.models.Graph], [`AgGrid`][vizro.models.AgGrid] and [`Table`][vizro.models.Table] models all have an argument called `figure`. This accepts a function (in the above example, `px.scatter`) that takes a pandas DataFrame as its first argument. The name of this argument is always `data_frame`. When configuring the dashboard using Python, it is optional to give the name of the argument: if you like, you could write `data_frame=iris` instead of `iris`.
-!!! note
+!!! note
With static data, once the dashboard is running, the data shown in the dashboard cannot change even if the source data in `iris.csv` changes. The code `iris = pd.read_csv("iris.csv")` is only executed once when the dashboard is first started. If you would like changes to source data to flow through to the dashboard then you must use [dynamic data](#dynamic-data).
### Reference by name
@@ -107,27 +106,27 @@ If you would like to specify your dashboard configuration through YAML then you
```
1. `"iris"` is the name of a data source added to the data manager. This data is a pandas DataFrame created by reading from the CSV file `iris.csv`.
+
=== "dashboard.yaml"
```yaml
pages:
- - components:
- - figure:
+ - components:
+ figure:
_target_: box
data_frame: iris # (1)!
x: species
y: petal_width
color: species
type: graph
- title: Static data example
+ title: Static data example
```
1. Refer to the `"iris"` data source in the data manager.
- === "Result"
- [![DataBasic]][DataBasic]
- [DataBasic]: ../../assets/user_guides/data/data_pandas_dataframe.png
+ === "Result"
+ [![DataBasic]][databasic]
-It is also possible to refer to a named data source using the Python API: `px.scatter("iris", ...)` or `px.scatter(data_frame="iris", ...)` would work if the `"iris"` data source has been registered in the data manager.
+It is also possible to refer to a named data source using the Python API: `px.scatter("iris", ...)` or `px.scatter(data_frame="iris", ...)` would work if the `"iris"` data source has been registered in the data manager.
## Dynamic data
@@ -166,14 +165,12 @@ The example below shows how data is fetched dynamically every time the page is r
```
1. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
- 2. To demonstrate that dynamic data can change when the page is refreshed, select 50 points at random. This simulates what would happen if your file `iris.csv` were constantly changing.
- 3. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()`; doing so would result in static data that cannot be reloaded.
- 4. Dynamic data is referenced by the name of the data source `"iris"`.
+ 1. To demonstrate that dynamic data can change when the page is refreshed, select 50 points at random. This simulates what would happen if your file `iris.csv` were constantly changing.
+ 1. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()`; doing so would result in static data that cannot be reloaded.
+ 1. Dynamic data is referenced by the name of the data source `"iris"`.
=== "Result"
- [![DynamicData]][DynamicData]
-
- [DynamicData]: ../../assets/user_guides/data/dynamic_data.gif
+ [![DynamicData]][dynamicdata]
Since dynamic data sources must always be added to the data manager and referenced by name, they may be used in YAML configuration [exactly the same way as for static data sources](#reference-by-name).
@@ -184,10 +181,10 @@ By default, a dynamic data function executes every time the dashboard is refresh
The Vizro data manager has a server-side caching mechanism to help solve this. Vizro's cache uses [Flask-Caching](https://flask-caching.readthedocs.io/en/latest/), which supports a number of possible cache backends and [configuration options](https://flask-caching.readthedocs.io/en/latest/#configuring-flask-caching). By default, the cache is turned off.
+
In a development environment the easiest way to enable caching is to use a [simple memory cache](https://cachelib.readthedocs.io/en/stable/simple/) with the default configuration options. This is achieved by adding one line to the above example to set `data_manager.cache`:
!!! example "Simple cache with default timeout of 5 minutes"
-
```py hl_lines="13"
from flask_caching import Cache
from vizro import Vizro
@@ -225,7 +222,6 @@ data_manager.cache = Cache(config={"CACHE_TYPE": "SimpleCache", "CACHE_DEFAULT_T
```
!!! warning
-
Simple cache exists purely for single-process development purposes and is not intended to be used in production. If you deploy with multiple workers, [for example with Gunicorn](run.md/#gunicorn), then you should use a production-ready cache backend. All of Flask-Caching's [built-in backends](https://flask-caching.readthedocs.io/en/latest/#built-in-cache-backends) other than `SimpleCache` are suitable for production. In particular, you might like to use [`FileSystemCache`](https://cachelib.readthedocs.io/en/stable/file/) or [`RedisCache`](https://cachelib.readthedocs.io/en/stable/redis/):
```py title="Production-ready caches"
@@ -239,7 +235,9 @@ data_manager.cache = Cache(config={"CACHE_TYPE": "SimpleCache", "CACHE_DEFAULT_T
Since Flask-Caching relies on [`pickle`](https://docs.python.org/3/library/pickle.html), which can execute arbitrary code during unpickling, you should not cache data from untrusted sources. Doing so [could be unsafe](https://github.com/pallets-eco/flask-caching/pull/209).
Note that when a production-ready cache backend is used, the cache is persisted beyond the Vizro process and is not cleared by restarting your server. To clear the cache then you must do so manually, for example, if you use `FileSystemCache` then you would delete your `cache` directory. Persisting the cache can also be useful for development purposes when handling data that takes a long time to load: even if you do not need the data to refresh while your dashboard is running, it can speed up your development loop to use dynamic data with a cache that is persisted between repeated runs of Vizro.
+
+
#### Set timeouts
You can change the timeout of the cache independently for each dynamic data source in the data manager using the `timeout` setting (measured in seconds). A `timeout` of 0 indicates that the cache does not expire. This is effectively the same as using [static data](#static-data).
@@ -278,8 +276,8 @@ In general, a parametrized dynamic data source should always return a pandas Dat
To add a parameter to control a dynamic data source, do the following:
1. add the appropriate argument to your dynamic data function and specify a default value for the argument.
-2. give an `id` to all components that have the data source you wish to alter through a parameter.
-3. [add a parameter](parameters.md) with `targets` of the form `.data_frame.` and a suitable [selector](selectors.md).
+1. give an `id` to all components that have the data source you wish to alter through a parameter.
+1. [add a parameter](parameters.md) with `targets` of the form `.data_frame.` and a suitable [selector](selectors.md).
For example, let us extend the [dynamic data example](#dynamic-data) above into an example of how parametrized dynamic data works. The `load_iris_data` can take an argument `number_of_points` controlled from the dashboard with a [`Slider`][vizro.models.Slider].
@@ -318,21 +316,18 @@ For example, let us extend the [dynamic data example](#dynamic-data) above into
```
1. `load_iris_data` takes a single argument, `number_of_points`, with a default value of 10.
- 2. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
- 3. Sample points at random, where `number_of_points` gives the number of points selected.
- 4. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()` or `load_iris_data(number_of_points=...)`; doing so would result in static data that cannot be reloaded.
- 5. Give the `vm.Graph` component `id="graph"` so that the `vm.Parameter` can target it. Dynamic data is referenced by the name of the data source `"iris"`.
- 6. Create a `vm.Parameter` to target the `number_of_points` argument for the `data_frame` used in `graph`.
+ 1. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
+ 1. Sample points at random, where `number_of_points` gives the number of points selected.
+ 1. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()` or `load_iris_data(number_of_points=...)`; doing so would result in static data that cannot be reloaded.
+ 1. Give the `vm.Graph` component `id="graph"` so that the `vm.Parameter` can target it. Dynamic data is referenced by the name of the data source `"iris"`.
+ 1. Create a `vm.Parameter` to target the `number_of_points` argument for the `data_frame` used in `graph`.
=== "Result"
- [![ParametrizedDynamicData]][ParametrizedDynamicData]
-
- [ParametrizedDynamicData]: ../../assets/user_guides/data/parametrized_dynamic_data.gif
+ [![ParametrizedDynamicData]][parametrizeddynamicdata]
Parametrized data loading is compatible with [caching](#configure-cache). The cache uses [memoization](https://flask-caching.readthedocs.io/en/latest/#memoization), so that the dynamic data function's arguments are included in the cache key. This means that `load_iris_data(number_of_points=10)` is cached independently of `load_iris_data(number_of_points=20)`.
!!! warning
-
You should always [treat the content of user input as untrusted](https://community.plotly.com/t/writing-secure-dash-apps-community-thread/54619). For example, you should not expose a filepath to load without passing it through a function like [`werkzeug.utils.secure_filename`](https://werkzeug.palletsprojects.com/en/3.0.x/utils/#werkzeug.utils.secure_filename), or you might enable arbitrary access to files on your server.
You cannot pass [nested parameters](parameters.md#nested-parameters) to dynamic data. You can only target the top-level arguments of the data loading function, not the nested keys in a dictionary.
@@ -354,7 +349,6 @@ When the page is refreshed, the behavior of a dynamic filter is as follows:
For example, let us add two filters to the [dynamic data example](#dynamic-data) above:
!!! example "Dynamic filters"
-
```py hl_lines="10 20 21"
from vizro import Vizro
import pandas as pd
@@ -386,8 +380,8 @@ For example, let us add two filters to the [dynamic data example](#dynamic-data)
```
1. We sample only 5 rather than 50 points so that changes to the available values in the filtered columns are more apparent when the page is refreshed.
- 2. This filter implicitly controls the dynamic data source `"iris"`, which supplies the `data_frame` to the targeted `vm.Graph`. On page refresh, Vizro reloads this data, finds all the unique values in the `"species"` column and sets the categorical selector's `options` accordingly.
- 3. Similarly, on page refresh, Vizro finds the minimum and maximum values of the `"sepal_length"` column in the reloaded data and sets new `min` and `max` values for the numerical selector accordingly.
+ 1. This filter implicitly controls the dynamic data source `"iris"`, which supplies the `data_frame` to the targeted `vm.Graph`. On page refresh, Vizro reloads this data, finds all the unique values in the `"species"` column and sets the categorical selector's `options` accordingly.
+ 1. Similarly, on page refresh, Vizro finds the minimum and maximum values of the `"sepal_length"` column in the reloaded data and sets new `min` and `max` values for the numerical selector accordingly.
Consider a filter that depends on dynamic data, where you do **not** want the available values to change when the dynamic data changes. You should manually specify the `selector`'s `options` field (categorical selector) or `min` and `max` fields (numerical selector). In the above example, this could be achieved as follows:
@@ -409,10 +403,13 @@ controls = [
When Vizro initially builds a filter that depends on parametrized dynamic data loading, data is loaded using the default argument values. This data is used to:
-* perform initial validation
-* check which data sources contain the specified `column` (unless `targets` is explicitly specified) and
-* find the type of selector to use (unless `selector` is explicitly specified).
+- perform initial validation
+- check which data sources contain the specified `column` (unless `targets` is explicitly specified) and
+- find the type of selector to use (unless `selector` is explicitly specified).
!!! note
-
When the value of a dynamic data parameter is changed by a dashboard user, the data underlying a dynamic filter can change. Currently this change affects page components such as `vm.Graph` but does not affect the available values shown in a dynamic filter, which only update on page refresh. This functionality will be coming soon!
+
+[databasic]: ../../assets/user_guides/data/data_pandas_dataframe.png
+[dynamicdata]: ../../assets/user_guides/data/dynamic_data.gif
+[parametrizeddynamicdata]: ../../assets/user_guides/data/parametrized_dynamic_data.gif
diff --git a/vizro-core/docs/pages/user-guides/extensions.md b/vizro-core/docs/pages/user-guides/extensions.md
index 2c7efc9ac..74a740448 100644
--- a/vizro-core/docs/pages/user-guides/extensions.md
+++ b/vizro-core/docs/pages/user-guides/extensions.md
@@ -2,64 +2,49 @@
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).
+- **[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.
+- **[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.
-* **[CSS customizations](#css-customizations)**. You can add custom CSS to any Vizro dashboard, enabling users to deviate from the default styling and create a unique look and feel for their dashboard.
-
-* **[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
+- **[CSS customizations](#css-customizations)**. You can add custom CSS to any Vizro dashboard, enabling users to deviate from the default styling and create a unique look and feel for their dashboard.
+- **[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
-
+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)).
+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.
-
+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).
+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
+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:
+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
@@ -93,14 +78,12 @@ enabling an interaction between data points in a scatter plot and the content of
## CSS customizations
-Vizro is opinionated about visual formatting, and some elements, such as the layout of the navigation and controls,
-are fixed. You can customize some settings such as background colors, fonts, and other styles via CSS overrides.
+Vizro is opinionated about visual formatting, and some elements, such as the layout of the navigation and controls, are fixed. You can customize some settings such as background colors, fonts, and other styles via CSS overrides.
For more information, see our documentation on [customizing CSS](custom-css.md)
## 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
+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)
diff --git a/vizro-core/docs/pages/user-guides/figure.md b/vizro-core/docs/pages/user-guides/figure.md
index 0589fad3b..03bfa412a 100644
--- a/vizro-core/docs/pages/user-guides/figure.md
+++ b/vizro-core/docs/pages/user-guides/figure.md
@@ -1,26 +1,19 @@
# How to use figures
-This guide shows you how to add any [Dash component](https://dash.plotly.com/#open-source-component-libraries) that needs to be reactive to [filter](filters.md) and [parameter](parameters.md) controls.
-If you want to add a static Dash component to your page, use [custom components](custom-components.md) instead.
+This guide shows you how to add any [Dash component](https://dash.plotly.com/#open-source-component-libraries) that needs to be reactive to [filter](filters.md) and [parameter](parameters.md) controls. If you want to add a static Dash component to your page, use [custom components](custom-components.md) instead.
-[`Figure`][vizro.models.Figure] provides a flexible foundation for all types of reactive Dash components in Vizro.
-The [`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] and [`AgGrid`][vizro.models.AgGrid] components are
-specific implementations of `Figure`. They serve as intuitive shortcuts, embedding behaviors and interactions specific
-to their purposes.
+[`Figure`][vizro.models.Figure] provides a flexible foundation for all types of reactive Dash components in Vizro. The [`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] and [`AgGrid`][vizro.models.AgGrid] components are specific implementations of `Figure`. They serve as intuitive shortcuts, embedding behaviors and interactions specific to their purposes.
-If these more specific models already achieve what you need then they should be used in preference to
-the more generic `Figure`. Remember that it is possible to supply [custom charts](custom-charts.md) to `Graph`
-and [custom tables](custom-tables.md) to `Table`.
+If these more specific models already achieve what you need then they should be used in preference to the more generic `Figure`. Remember that it is possible to supply [custom charts](custom-charts.md) to `Graph` and [custom tables](custom-tables.md) to `Table`.
-There are already a few figure functions you can reuse, see the section on [KPI cards](#key-performance-indicator-kpi-cards)
-for more details:
+There are already a few figure functions you can reuse, see the section on [KPI cards](#key-performance-indicator-kpi-cards) for more details:
- [`kpi_card`][vizro.figures.kpi_card]
- [`kpi_card_reference`][vizro.figures.kpi_card_reference]
The following flowchart shows what you need to consider when choosing which model to use:
-``` mermaid
+```mermaid
graph TD
first["`Does your desired component exist in Vizro, e.g. Graph, Table or AgGrid?`"]
specific-component([Use the specific component])
@@ -40,14 +33,12 @@ graph TD
classDef clickable color:#4051b5;
```
-
To add a `Figure` to your page:
1. Add the `Figure` model to the components argument of the [Page][vizro.models.Page] model.
-2. Use an existing figure function from [`vizro.figures`](../API-reference/figure-callables.md) and pass it to the `figure` argument of the `Figure` model.
+1. Use an existing figure function from [`vizro.figures`](../API-reference/figure-callables.md) and pass it to the `figure` argument of the `Figure` model.
!!! example "Use existing figure functions"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -99,40 +90,25 @@ To add a `Figure` to your page:
selector:
type: radio_items
layout:
- grid:
- [
- [0, -1, -1, -1],
- [-1, -1, -1, -1],
- [-1, -1, -1, -1],
- [-1, -1, -1, -1],
- [-1, -1, -1, -1],
- ]
+ grid: [[0, -1, -1, -1], [-1, -1, -1, -1], [-1, -1, -1, -1], [-1, -1, -1, -1],
+ [-1, -1, -1, -1]]
title: KPI card
```
- === "Result"
- [![Figure]][Figure]
-
- [Figure]: ../../assets/user_guides/figure/figure.png
+ === "Result"
+ [![Figure]][figure]
### Key Performance Indicator (KPI) cards
-A KPI card is a dynamic card that can display a single value, but optionally, can also include a title, icon, and reference value.
-It is a common visual component to display key metrics in a dashboard. Vizro supports two pre-defined KPI card functions:
-- [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card): A KPI card that shows a single value found
-by performing an aggregation function (by default, `sum`) over a specified column.
-Required arguments are `data_frame` and `value_column`.
+A KPI card is a dynamic card that can display a single value, but optionally, can also include a title, icon, and reference value. It is a common visual component to display key metrics in a dashboard. Vizro supports two pre-defined KPI card functions:
-- [`kpi_card_with_reference`](../API-reference/figure-callables.md#vizro.figures.kpi_card_reference): A KPI card that shows a single value
-and a delta comparison to a reference value found by performing an aggregation function (by default, `sum`) over the specified columns.
-Required arguments are `data_frame`, `value_column` and `reference_column`.
+- [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card): A KPI card that shows a single value found by performing an aggregation function (by default, `sum`) over a specified column. Required arguments are `data_frame` and `value_column`.
-As described in the [API reference](../API-reference/figure-callables.md) and illustrated in the below example, these
-functions have several arguments to customize your KPI cards. If you require a level of customization that is not
-possible with the built-in functions then you can create a [custom figure](custom-figures.md).
+- [`kpi_card_with_reference`](../API-reference/figure-callables.md#vizro.figures.kpi_card_reference): A KPI card that shows a single value and a delta comparison to a reference value found by performing an aggregation function (by default, `sum`) over the specified columns. Required arguments are `data_frame`, `value_column` and `reference_column`.
-!!! example "KPI card variations"
+As described in the [API reference](../API-reference/figure-callables.md) and illustrated in the below example, these functions have several arguments to customize your KPI cards. If you require a level of customization that cannot be done with the built-in functions then you can create a [custom figure](custom-figures.md).
+!!! example "KPI card variations"
=== "app.py"
```{.python pycafe-link}
import pandas as pd
@@ -258,8 +234,8 @@ possible with the built-in functions then you can create a [custom figure](custo
value_column: Actual
reference_column: Reference
title: KPI reference with formatting
- value_format: "{value:.2f}€"
- reference_format: "{delta:+.2f}€ vs. last year ({reference:.2f}€)"
+ value_format: '{value:.2f}€'
+ reference_format: '{delta:+.2f}€ vs. last year ({reference:.2f}€)'
type: figure
- figure:
_target_: kpi_card_reference
@@ -276,7 +252,9 @@ possible with the built-in functions then you can create a [custom figure](custo
grid: [[0, 1, 2, 3], [4, 5, 6, 7], [-1, -1, -1, -1], [-1, -1, -1, -1]]
title: KPI cards
```
+
=== "Result"
- [![KPICards]][KPICards]
+ [![KPICards]][kpicards]
- [KPICards]: ../../assets/user_guides/figure/kpi_cards.png
+[figure]: ../../assets/user_guides/figure/figure.png
+[kpicards]: ../../assets/user_guides/figure/kpi_cards.png
diff --git a/vizro-core/docs/pages/user-guides/filters.md b/vizro-core/docs/pages/user-guides/filters.md
index bc3649178..8228ecbe7 100644
--- a/vizro-core/docs/pages/user-guides/filters.md
+++ b/vizro-core/docs/pages/user-guides/filters.md
@@ -2,8 +2,7 @@
This guide shows you how to add filters to your dashboard. One main way to interact with the charts/components on your page is by filtering the underlying data. A filter selects a subset of rows of a component's underlying DataFrame which alters the appearance of that component on the page.
-The [`Page`][vizro.models.Page] model accepts the `controls` argument, where you can enter a [`Filter`][vizro.models.Filter] model.
-This model enables the automatic creation of [selectors](selectors.md) (for example, `Dropdown` or `RangeSlider`) that operate on the charts/components on the screen.
+The [`Page`][vizro.models.Page] model accepts the `controls` argument, where you can enter a [`Filter`][vizro.models.Filter] model. This model enables the automatic creation of [selectors](selectors.md) (for example, `Dropdown` or `RangeSlider`) that operate on the charts/components on the screen.
By default, filters that control components with [dynamic data](data.md#dynamic-data) are [dynamically updated](data.md#filters) when the underlying data changes while the dashboard is running.
@@ -12,7 +11,7 @@ By default, filters that control components with [dynamic data](data.md#dynamic-
To add a filter to your page, do the following:
1. add the [`Filter`][vizro.models.Filter] model into the `controls` argument of the [`Page`][vizro.models.Page] model
-2. configure the `column` argument, which denotes the target column to be filtered
+1. configure the `column` argument, which denotes the target column to be filtered
You can also set `targets` to specify which components on the page the filter should apply to. If this is not explicitly set then `targets` defaults to all components on the page whose data source includes `column`.
@@ -39,6 +38,7 @@ You can also set `targets` to specify which components on the page the filter sh
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -57,17 +57,15 @@ You can also set `targets` to specify which components on the page the filter sh
type: filter
title: My first page
```
- === "Result"
- [![Filter]][Filter]
-
- [Filter]: ../../assets/user_guides/control/control1.png
+ === "Result"
+ [![Filter]][filter]
The selector is configured automatically based on the target column type data as follows:
- - Categorical data uses [`vm.Dropdown(multi=True)`][vizro.models.Dropdown] where `options` is the set of unique values found in `column` across all the data sources of components in `targets`.
- - [Numerical data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_numeric_dtype.html) uses [`vm.RangeSlider`][vizro.models.RangeSlider] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`.
- - [Temporal data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_datetime64_any_dtype.html) uses [`vm.DatePicker(range=True)`][vizro.models.DatePicker] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`. A column can be converted to this type with [pandas.to_datetime](https://pandas.pydata.org/docs/reference/api/pandas.to_datetime.html).
+- Categorical data uses [`vm.Dropdown(multi=True)`][vizro.models.Dropdown] where `options` is the set of unique values found in `column` across all the data sources of components in `targets`.
+- [Numerical data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_numeric_dtype.html) uses [`vm.RangeSlider`][vizro.models.RangeSlider] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`.
+- [Temporal data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_datetime64_any_dtype.html) uses [`vm.DatePicker(range=True)`][vizro.models.DatePicker] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`. A column can be converted to this type with [pandas.to_datetime](https://pandas.pydata.org/docs/reference/api/pandas.to_datetime.html).
The following example demonstrates these default selector types.
@@ -107,6 +105,7 @@ The following example demonstrates these default selector types.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -129,15 +128,13 @@ The following example demonstrates these default selector types.
type: filter
title: My first page
```
- === "Result"
- [![Filter]][Filter]
- [Filter]: ../../assets/user_guides/selectors/default_filter_selectors.png
+ === "Result"
+ [![Filter]][filter]
## Change selector
-If you want to have a different selector for your filter, you can give the `selector` argument of the [`Filter`][vizro.models.Filter] a different selector model.
-Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropdown`][vizro.models.Dropdown], [`RadioItems`][vizro.models.RadioItems], [`RangeSlider`][vizro.models.RangeSlider], [`Slider`][vizro.models.Slider], and [`DatePicker`][vizro.models.DatePicker].
+If you want to have a different selector for your filter, you can give the `selector` argument of the [`Filter`][vizro.models.Filter] a different selector model. Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropdown`][vizro.models.Dropdown], [`RadioItems`][vizro.models.RadioItems], [`RangeSlider`][vizro.models.RangeSlider], [`Slider`][vizro.models.Slider], and [`DatePicker`][vizro.models.DatePicker].
!!! example "Filter with different selector"
=== "app.py"
@@ -162,6 +159,7 @@ Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropd
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -181,11 +179,9 @@ Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropd
type: filter
title: My first page
```
- === "Result"
-
- [![Selector]][Selector]
- [Selector]: ../../assets/user_guides/control/control2.png
+ === "Result"
+ [![Selector]][selector]
## Further customization
@@ -220,6 +216,7 @@ Below is an advanced example where we only target one page component, and where
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -244,17 +241,19 @@ Below is an advanced example where we only target one page component, and where
controls:
- column: petal_length
targets:
- - scatter_chart
+ - scatter_chart
selector:
step: 1
type: range_slider
type: filter
title: My first page
```
- === "Result"
-
- [![Advanced]][Advanced]
- [Advanced]: ../../assets/user_guides/control/control3.png
+ === "Result"
+ [![Advanced]][advanced]
To further customize selectors, see our [how-to-guide on creating custom components](custom-components.md).
+
+[advanced]: ../../assets/user_guides/control/control3.png
+[filter]: ../../assets/user_guides/control/control1.png
+[selector]: ../../assets/user_guides/control/control2.png
diff --git a/vizro-core/docs/pages/user-guides/graph.md b/vizro-core/docs/pages/user-guides/graph.md
index 36c670997..1c3ffc8bc 100755
--- a/vizro-core/docs/pages/user-guides/graph.md
+++ b/vizro-core/docs/pages/user-guides/graph.md
@@ -6,25 +6,18 @@ The [`Graph`][vizro.models.Graph] model is the most used component in many dashb
To add a [`Graph`][vizro.models.Graph] to your page, do the following:
-1. insert the [`Graph`][vizro.models.Graph] model into the `components` argument of the
-[`Page`][vizro.models.Page] model
-2. enter any of the currently available charts of the open source library [`plotly.express`](https://plotly.com/python/plotly-express/) into the `figure` argument
+1. insert the [`Graph`][vizro.models.Graph] model into the `components` argument of the [`Page`][vizro.models.Page] model
+1. enter any of the currently available charts of the open source library [`plotly.express`](https://plotly.com/python/plotly-express/) into the `figure` argument
!!! note
+ To use the [`plotly.express`](https://plotly.com/python/plotly-express/) chart in a Vizro dashboard, you need to import it as `import vizro.plotly.express as px`. This leaves any of the [`plotly.express`](https://plotly.com/python/plotly-express/) functionality untouched yet enables _direct insertion_ into the [`Graph`][vizro.models.Graph] model _as is_.
- In order to use the [`plotly.express`](https://plotly.com/python/plotly-express/) chart in a Vizro dashboard, you need to import it as `import vizro.plotly.express as px`.
- This leaves any of the [`plotly.express`](https://plotly.com/python/plotly-express/) functionality untouched, but allows _direct insertion_ into the [`Graph`][vizro.models.Graph] model _as is_.
-
- Note also that the `plotly.express` chart needs to have a `data_frame` argument. In case you require a chart without
- a `data_frame` argument (for example, the [`imshow` chart](https://plotly.com/python/imshow/)), refer to our
- [guide on custom charts](custom-charts.md).
-
+ Note also that the `plotly.express` chart needs to have a `data_frame` argument. In case you require a chart without a `data_frame` argument (for example, the [`imshow` chart](https://plotly.com/python/imshow/)), refer to our [guide on custom charts](custom-charts.md).
## Insert Plotly chart
!!! example "Graph"
=== "app.py"
-
```{.python pycafe-link}
import vizro.models as vm
import vizro.plotly.express as px
@@ -47,25 +40,24 @@ To add a [`Graph`][vizro.models.Graph] to your page, do the following:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: scatter_matrix
- color: species
- data_frame: iris
- dimensions: ["sepal_length", "sepal_width", "petal_length", "petal_width"]
- type: graph
- title: My first page
+ - components:
+ - figure:
+ _target_: scatter_matrix
+ color: species
+ data_frame: iris
+ dimensions: [sepal_length, sepal_width, petal_length, petal_width]
+ type: graph
+ title: My first page
```
- === "Result"
- [![Graph]][Graph]
-
- [Graph]: ../../assets/user_guides/components/graph.png
+ === "Result"
+ [![Graph]][graph]
In the Python example we directly inserted the pandas DataFrame `df` into `figure=px.scatter_matrix(df, ...)`. This is [one way to supply data to a chart](data.md#supply-directly). For the YAML version, we [refer to the data source by name](data.md#reference-by-name) as `data_frame: iris`. For a full explanation of the different methods you can use to send data to your dashboard, see [our guide to using data in Vizro](data.md).
@@ -73,31 +65,24 @@ In the Python example we directly inserted the pandas DataFrame `df` into `figur
You will need to create a custom chart if you want to customize the Plotly chart beyond a function call, for example by:
-* using post-update methods like `update_layout`, `update_xaxes`, `update_traces`, or
-* by creating a custom `plotly.graph_objects.Figure()` object and manually adding traces with `add_trace`.
-
-For more details, refer to our [user guide on custom chart](custom-charts.md) and the
-[Plotly documentation on updating figures](https://plotly.com/python/creating-and-updating-figures/).
+- using post-update methods like `update_layout`, `update_xaxes`, `update_traces`, or
+- by creating a custom `plotly.graph_objects.Figure()` object and manually adding traces with `add_trace`.
+For more details, refer to our [user guide on custom chart](custom-charts.md) and the [Plotly documentation on updating figures](https://plotly.com/python/creating-and-updating-figures/).
## Add title, header, and footer
-The [`Graph`][vizro.models.Graph] accepts a `title`, `header` and `footer` argument. This is useful for providing
-context to the data being displayed, or for adding a description of the data.
+The [`Graph`][vizro.models.Graph] accepts a `title`, `header` and `footer` argument. This is useful for context on the data being displayed, or for adding a description of the data.
- **title**: Displayed as an [H3 header](https://dash.plotly.com/dash-html-components/h3), useful for summarizing the main topic or insight of the component.
- **header**: Accepts markdown text, ideal for extra descriptions, subtitles, or detailed data insights.
- **footer**: Accepts markdown text, commonly used for citing data sources, providing information on the last update, or adding disclaimers.
-
!!! note
-
- Although you can directly provide a `title` to the Plotly Express chart, we recommend using `Graph.title` for
- proper alignment with other components on the screen.
+ Although you can directly give a `title` to the Plotly Express chart, we recommend using `Graph.title` for proper alignment with other components on the screen.
!!! example "Formatted Graph"
=== "app.py"
-
```{.python pycafe-link}
import vizro.models as vm
@@ -126,31 +111,34 @@ context to the data being displayed, or for adding a description of the data.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: scatter
- x: sepal_width
- y: sepal_length
- color: species
- data_frame: iris
- title: Relationships between Sepal Width and Sepal Length
- header: |
- Each point in the scatter plot represents one of the 150 iris flowers, with colors indicating their
- types. The Setosa type is easily identifiable by its short and wide sepals.
-
- However, there is still overlap between the Versicolor and Virginica types when considering only sepal
- width and length.
- footer: |
- SOURCE: **Plotly iris data set, 2024**
- type: graph
- title: Formatted Graph
+ - components:
+ - figure:
+ _target_: scatter
+ x: sepal_width
+ y: sepal_length
+ color: species
+ data_frame: iris
+ title: Relationships between Sepal Width and Sepal Length
+ header: |
+ Each point in the scatter plot represents one of the 150 iris flowers, with colors indicating their
+ types. The Setosa type is easily identifiable by its short and wide sepals.
+
+ However, there is still overlap between the Versicolor and Virginica types when considering only sepal
+ width and length.
+ footer: |
+ SOURCE: **Plotly iris data set, 2024**
+ type: graph
+ title: Formatted Graph
```
+
=== "Result"
- [![FormattedGraph]][FormattedGraph]
+ [![FormattedGraph]][formattedgraph]
- [FormattedGraph]: ../../assets/user_guides/components/formatted_graph.png
+[formattedgraph]: ../../assets/user_guides/components/formatted_graph.png
+[graph]: ../../assets/user_guides/components/graph.png
diff --git a/vizro-core/docs/pages/user-guides/install.md b/vizro-core/docs/pages/user-guides/install.md
index 4d4c01239..6a07911e5 100644
--- a/vizro-core/docs/pages/user-guides/install.md
+++ b/vizro-core/docs/pages/user-guides/install.md
@@ -8,8 +8,8 @@ We recommend that you create a virtual environment for each Vizro project you wo
## Prerequisites to working locally
-* **Python**: Vizro supports macOS, Linux, and Windows. It works with Python 3.9 and later.
-* **Virtual environment**: You specify the version of Python to use with Vizro when you set up the virtual environment. See the following references to learn more about [Python virtual environments](https://realpython.com/python-virtual-environments-a-primer/), [Conda virtual environments](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#starting-conda) or [watch an explainer video about them](https://youtu.be/YKfAwIItO7M).
+- **Python**: Vizro supports macOS, Linux, and Windows. It works with Python 3.9 and later.
+- **Virtual environment**: You specify the version of Python to use with Vizro when you set up the virtual environment. See the following references to learn more about [Python virtual environments](https://realpython.com/python-virtual-environments-a-primer/), [Conda virtual environments](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#starting-conda) or [watch an explainer video about them](https://youtu.be/YKfAwIItO7M).
### How to create a virtual environment for your Vizro project
diff --git a/vizro-core/docs/pages/user-guides/kedro-data-catalog.md b/vizro-core/docs/pages/user-guides/kedro-data-catalog.md
index 0e2b0954e..ce4b060fa 100644
--- a/vizro-core/docs/pages/user-guides/kedro-data-catalog.md
+++ b/vizro-core/docs/pages/user-guides/kedro-data-catalog.md
@@ -3,6 +3,7 @@
This page describes how to integrate Vizro with [Kedro](https://docs.kedro.org/en/stable/index.html), an open-source Python framework to create reproducible, maintainable, and modular data science code. For Pandas datasets registered in a Kedro data catalog, Vizro provides a convenient way to visualize them.
## Installation
+
If you already have Kedro installed then you do not need to install any extra dependencies. If you do not have Kedro installed then you should run:
```bash
@@ -10,7 +11,9 @@ pip install vizro[kedro]
```
## Use datasets from the Kedro Data Catalog
+
`vizro.integrations.kedro` provides functions to help generate and process a [Kedro Data Catalog](https://docs.kedro.org/en/stable/data/index.html). Given a Kedro Data Catalog `catalog`, the general pattern to add datasets into the Vizro data manager is:
+
```python
from vizro.integrations import kedro as kedro_integration
from vizro.managers import data_manager
@@ -25,15 +28,14 @@ This imports all datasets of type [`kedro_datasets.pandas`](https://docs.kedro.o
The `catalog` variable may have been created in a number of different ways:
1. Kedro project path. Vizro exposes a helper function `vizro.integrations.kedro.catalog_from_project` to generate a `catalog` given the path to a Kedro project.
-2. [Kedro Jupyter session](https://docs.kedro.org/en/stable/notebooks_and_ipython/kedro_and_notebooks.html). This automatically exposes `catalog`.
-3. Data Catalog configuration file (`catalog.yaml`). This can create a `catalog` entirely independently of a Kedro project using [`kedro.io.DataCatalog.from_config`](https://docs.kedro.org/en/stable/kedro.io.DataCatalog.html#kedro.io.DataCatalog.from_config).
+1. [Kedro Jupyter session](https://docs.kedro.org/en/stable/notebooks_and_ipython/kedro_and_notebooks.html). This automatically exposes `catalog`.
+1. Data Catalog configuration file (`catalog.yaml`). This can create a `catalog` entirely independently of a Kedro project using [`kedro.io.DataCatalog.from_config`](https://docs.kedro.org/en/stable/kedro.io.DataCatalog.html#kedro.io.DataCatalog.from_config).
The full code for these different cases is given below.
!!! example "Import a Kedro Data Catalog into the Vizro data manager"
-
=== "app.py (Kedro project path)"
- ```py
+ ```python
from vizro.integrations import kedro as kedro_integration
from vizro.managers import data_manager
@@ -43,16 +45,18 @@ The full code for these different cases is given below.
for dataset_name, dataset in kedro_integration.datasets_from_catalog(catalog).items():
data_manager[dataset_name] = dataset
```
+
=== "app.ipynb (Kedro Jupyter session)"
- ```py
+ ```python
from vizro.managers import data_manager
for dataset_name, dataset in kedro_integration.datasets_from_catalog(catalog).items():
data_manager[dataset_name] = dataset
```
+
=== "app.py (Data Catalog configuration file)"
- ```py
+ ```python
from kedro.io import DataCatalog
import yaml
diff --git a/vizro-core/docs/pages/user-guides/layouts.md b/vizro-core/docs/pages/user-guides/layouts.md
index 8361560db..af66ec301 100644
--- a/vizro-core/docs/pages/user-guides/layouts.md
+++ b/vizro-core/docs/pages/user-guides/layouts.md
@@ -3,11 +3,10 @@
The [`Page`][vizro.models.Page] model accepts a `layout` argument that enables custom arrangement of charts and components on the screen. This guide shows how to customize the grid specifications in the [`Layout`][vizro.models.Layout].
## The default layout
-The `layout` argument of the [`Page`][vizro.models.Page] model is optional. If no layout is specified, all charts/components are automatically [**stacked vertically**](layouts.md#vertical-and-horizontal-stacking) on the page in one column.
-If you are happy with that arrangement, you can create your charts/components without providing a [`Layout`][vizro.models.Layout].
-!!! example "Default Layout"
+The `layout` argument of the [`Page`][vizro.models.Page] model is optional. If no layout is specified, all charts/components are automatically [**stacked vertically**](layouts.md#vertical-and-horizontal-stacking) on the page in one column. If you are happy with that arrangement, you can create your charts/components without providing a [`Layout`][vizro.models.Layout].
+!!! example "Default Layout"
=== "app.py"
```{.python pycafe-link}
from vizro import Vizro
@@ -23,35 +22,33 @@ If you are happy with that arrangement, you can create your charts/components wi
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- title: two_left
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ title: two_left
```
- === "Result"
- [![Layout]][Layout]
-
- [Layout]: ../../assets/user_guides/layout/two_left.png
-
+ === "Result"
+ [![Layout]][layout]
## Configure the grid
+
To customize the grid arrangement, configure the `grid` parameter of the [`Layout`][vizro.models.Layout] model.
The example below shows an example of a valid `grid`:
```python title="Basic example"
-grid = [[0, 1],
- [0, 2]]
+grid = [[0, 1], [0, 2]]
```
- The `grid` must be provided as `list[list[int]]` (for example, `grid = [[0, 1], [0, 2]]`).
@@ -64,16 +61,12 @@ grid = [[0, 1],
- The area spanned by a chart/component in the grid must be rectangular.
- The grid can be arbitrarily large, allowing arbitrarily granular control of the grid.
-
## Vertical and horizontal stacking
+
As described above, when no `Layout` is specified, components are presented **vertically** as a single-column stack. If you have three components, the default `Layout.grid` will be as follows, with three equally sized rows, each containing a component spanning the entire width:
```python title="Vertical stacking"
-grid = [
- [0],
- [1],
- [2]
- ]
+grid = [[0], [1], [2]]
```
To present components **horizontally** in one row:
@@ -89,8 +82,8 @@ This defines a single row that occupies the entire width and height, divided int
## Grid - basic example
-!!! example "Grid Arrangement - Basic Example"
+!!! example "Grid Arrangement - Basic Example"
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -109,39 +102,37 @@ This defines a single row that occupies the entire width and height, divided int
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- - text: |
- # Component 2
- type: card
- layout:
- grid: [[0, 1], [0, 2]]
- title: one_left_two_right
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ layout:
+ grid: [[0, 1], [0, 2]]
+ title: one_left_two_right
```
- === "Result"
- [![Grid]][Grid]
- [Grid]: ../../assets/user_guides/layout/one_left_two_right.png
+ === "Result"
+ [![Grid]][grid]
## Grid - advanced example
If you want to divide the grid into subgrids with finer control over these, you can use [`Containers`](container.md). See our section on [when to use `Containers` vs. `Page.layout`](container.md#when-to-use-containers) for more information.
-The `Layout` provides full control over the arrangement of top-level components within a page,
-allowing arbitrarily granular control of the grid by creating larger grids.
+The `Layout` provides full control over the arrangement of top-level components within a page, allowing arbitrarily granular control of the grid by creating larger grids.
!!! example "Grid Arrangement - Advanced Example"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -208,6 +199,7 @@ allowing arbitrarily granular control of the grid by creating larger grids.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -260,44 +252,44 @@ allowing arbitrarily granular control of the grid by creating larger grids.
grid: [[0, 1, 3, 4], [2, 2, 3, 4]]
title: Custom Layout - Advanced Example
```
- === "Result"
- [![GridAdv]][GridAdv]
- [GridAdv]: ../../assets/user_guides/layout/grid_advanced.png
+ === "Result"
+ [![GridAdv]][gridadv]
## Custom layout examples
+
Here is a reference table of example layouts:
+
one row with one component, second row with two components stacked horizontally
-| Layout needed | Grid | Code |
-|--------------------------------|----------------------------|-------------------------------------------------------------------------------------|
-| | | `layout=vm.Layout(grid=[[0]])` |
-| | | `layout=vm.Layout(grid=[[0],[1]])` |
-| | | `layout=vm.Layout(grid=[[0,1]])` |
-| | | `layout=vm.Layout(grid=[[0],[1],[2]])` or
`layout=None` |
-| | | `layout=vm.Layout(grid=[[0,1],[0,2]])` |
-| | | `layout=vm.Layout(grid=[[0,0],[1,2]])` |
-| | | `layout=vm.Layout(grid=[[0,1],[2,2]])` |
-| | | `layout=vm.Layout(grid=[[0,1],[0,2],[0,3]])` |
-| | | `layout=vm.Layout(grid=[[0,1],[2,3]])` |
-| | | `layout=vm.Layout(grid=[[0,3],[1,3],[2,3]])` |
-| | | `layout=vm.Layout(grid=[[0,0,0],[1,2,3]])` |
-| | | `layout=vm.Layout(grid=[[0,1,2],[3,3,3]])` |
+| Layout needed | Grid | Code |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| | | `layout=vm.Layout(grid=[[0]])` |
+| | | `layout=vm.Layout(grid=[[0],[1]])` |
+| | | `layout=vm.Layout(grid=[[0,1]])` |
+| | | `layout=vm.Layout(grid=[[0],[1],[2]])` or
`layout=None` |
+| | | `layout=vm.Layout(grid=[[0,1],[0,2]])` |
+| | | `layout=vm.Layout(grid=[[0,0],[1,2]])` |
+| | | `layout=vm.Layout(grid=[[0,1],[2,2]])` |
+| | | `layout=vm.Layout(grid=[[0,1],[0,2],[0,3]])` |
+| | | `layout=vm.Layout(grid=[[0,1],[2,3]])` |
+| | | `layout=vm.Layout(grid=[[0,3],[1,3],[2,3]])` |
+| | | `layout=vm.Layout(grid=[[0,0,0],[1,2,3]])` |
+| | | `layout=vm.Layout(grid=[[0,1,2],[3,3,3]])` |
## Add empty sections to the grid
+
One approach to organize the dashboard's layout involves integrating empty sections by specifying `-1` within the grid layout.
```python title="Example"
-grid = [[0, 1, -1],
- [0, 2, -1]]
+grid = [[0, 1, -1], [0, 2, -1]]
```
!!! example "Adding Empty Spaces"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -316,38 +308,38 @@ grid = [[0, 1, -1],
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- - text: |
- # Component 2
- type: card
- layout:
- grid: [[0, 1, -1], [0, 2, -1]]
- title: Adding empty spaces
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ layout:
+ grid: [[0, 1, -1], [0, 2, -1]]
+ title: Adding empty spaces
```
- === "Result"
- [![GridEmpty]][GridEmpty]
- [GridEmpty]: ../../assets/user_guides/layout/layout_empty_spaces.png
+ === "Result"
+ [![GridEmpty]][gridempty]
## Control the scroll behavior
+
By default, the grid fits all charts/components on the screen. This can lead to distortions such that the chart/component looks squashed. To control the scroll behavior, you can specify the following:
- `row_min_height`: Sets a chart/component's minimum height. Defaults to 0px.
- `col_min_width`: Sets a chart/component's minimum width. Defaults to 0px.
!!! example "Activate Scrolling"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -371,59 +363,63 @@ By default, the grid fits all charts/components on the screen. This can lead to
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- - text: |
- # Component 2
- type: card
- - text: |
- # Component 2
- type: card
- - text: |
- # Component 4
- type: card
- - text: |
- # Component 5
- type: card
- - text: |
- # Component 6
- type: card
- - text: |
- # Component 7
- type: card
- layout:
- grid: [[0], [1], [2], [3], [4], [5], [6], [7]]
- row_min_height: 240px
- title: Activate scrolling
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ - text: |
+ # Component 4
+ type: card
+ - text: |
+ # Component 5
+ type: card
+ - text: |
+ # Component 6
+ type: card
+ - text: |
+ # Component 7
+ type: card
+ layout:
+ grid: [[0], [1], [2], [3], [4], [5], [6], [7]]
+ row_min_height: 240px
+ title: Activate scrolling
```
- === "Result"
- [![GridScroll]][GridScroll]
-
- [GridScroll]: ../../assets/user_guides/layout/grid_scroll.png
+ === "Result"
+ [![GridScroll]][gridscroll]
## Further customization
-For further customization, such as changing the gap between row and column, refer to the
-documentation of the [`Layout`][vizro.models.Layout] model.
+
+For further customization, such as changing the gap between row and column, refer to the documentation of the [`Layout`][vizro.models.Layout] model.
## Alternative layout approaches
+
In general, any arbitrarily granular layout can already be achieved using [`Page.layout`](layouts.md) alone and is our recommended approach if you want to arrange components on a page with consistent row and/or column spacing.
!!! note "Alternative layout approaches: `Tabs` and `Containers`"
-
- [`Tabs`][vizro.models.Tabs] and [`Containers`][vizro.models.Container] provide an alternative approach to customize your page layout.
- For example, if you want to have more granular control and break the overall page grid into subgrids, see our [user guide on Containers](container.md).
+ [`Tabs`][vizro.models.Tabs] and [`Containers`][vizro.models.Container] offer an alternative approach to customize your page layout. For example, if you want to have more granular control and break the overall page grid into subgrids, see our [user guide on Containers](container.md).
If you want to display multiple containers on one page by putting them into the same screen space, and letting the user switch between them, see our [user guide on Tabs](tabs.md).
{ width="500" }
+
+[grid]: ../../assets/user_guides/layout/one_left_two_right.png
+[gridadv]: ../../assets/user_guides/layout/grid_advanced.png
+[gridempty]: ../../assets/user_guides/layout/layout_empty_spaces.png
+[gridscroll]: ../../assets/user_guides/layout/grid_scroll.png
+[layout]: ../../assets/user_guides/layout/two_left.png
diff --git a/vizro-core/docs/pages/user-guides/navigation.md b/vizro-core/docs/pages/user-guides/navigation.md
index 41c6bb9dc..75a661470 100644
--- a/vizro-core/docs/pages/user-guides/navigation.md
+++ b/vizro-core/docs/pages/user-guides/navigation.md
@@ -2,8 +2,7 @@
This guide shows you how to use and customize the navigation that appears on the left of your dashboard.
-The [`Dashboard`][vizro.models.Dashboard] model accepts a `navigation` argument, where you can enter a [`Navigation`][vizro.models.Navigation] model. This enables you to group pages together and customize how they appear in your navigation.
-The dashboard includes a collapsible side panel that users can minimize or expand by a button click. The collapse button, located in the top right corner of the side panel, is visible by default for user convenience.
+The [`Dashboard`][vizro.models.Dashboard] model accepts a `navigation` argument, where you can enter a [`Navigation`][vizro.models.Navigation] model. This enables you to group pages together and customize how they appear in your navigation. The dashboard includes a collapsible side panel that users can minimize or expand by a button click. The collapse button, located in the top right corner of the side panel, is visible by default for user convenience.
## Use the default navigation
@@ -56,8 +55,8 @@ By default, if the `navigation` argument is not specified, Vizro creates a navig
type: graph
title: My first page
- components:
- - text: My text here
- type: card
+ - text: My text here
+ type: card
title: My second page
- components:
- figure:
@@ -69,10 +68,9 @@ By default, if the `navigation` argument is not specified, Vizro creates a navig
type: graph
title: My third page
```
- === "Result"
- [![DefaultNavigation]][DefaultNavigation]
- [DefaultNavigation]: ../../assets/user_guides/navigation/default_navigation.png
+ === "Result"
+ [![DefaultNavigation]][defaultnavigation]
## Include a subset of pages
@@ -132,17 +130,15 @@ To include only some of your dashboard pages in your navigation then list them i
- My first page
- My second page
```
- === "Result"
- [![OnlySomePages]][OnlySomePages]
- [OnlySomePages]: ../../assets/user_guides/navigation/only_some_pages.png
+ === "Result"
+ [![OnlySomePages]][onlysomepages]
## Group pages
You can also group your pages together by specifying `pages` as a dictionary:
!!! example "Grouping pages"
-
=== "snippet.py"
```py
# page_1, page_2, page_3 defined as in default example
@@ -154,7 +150,6 @@ You can also group your pages together by specifying `pages` as a dictionary:
```
=== "app.py"
-
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -187,6 +182,7 @@ You can also group your pages together by specifying `pages` as a dictionary:
)
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -200,18 +196,15 @@ You can also group your pages together by specifying `pages` as a dictionary:
Group B:
- My third page
```
- === "Result"
- [![GroupedNavigation]][GroupedNavigation]
-
- [GroupedNavigation]: ../../assets/user_guides/navigation/grouped_navigation.png
+ === "Result"
+ [![GroupedNavigation]][groupednavigation]
## Use a navigation bar with icons
Another way to group together pages in the navigation is to use a [`NavBar`][vizro.models.NavBar] with icons. The simplest way to use this is to change the `nav_selector` specified in [`Navigation`][vizro.models.Navigation]:
!!! example "Using `NavBar`"
-
=== "snippet.py"
```py
# page_1, page_2, page_3 defined as in default example
@@ -223,8 +216,8 @@ Another way to group together pages in the navigation is to use a [`NavBar`][viz
)
Vizro().build(dashboard).run()
```
- === "app.py"
+ === "app.py"
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -276,14 +269,11 @@ Another way to group together pages in the navigation is to use a [`NavBar`][viz
nav_selector:
type: nav_bar
```
- === "Result"
- [![NavBar]][NavBar]
-
- [NavBar]: ../../assets/user_guides/navigation/nav_bar.png
+ === "Result"
+ [![NavBar]][navbar]
-Here, the first level of the navigation hierarchy ("Group A" and "Group B") is represented by an icon in a navigation bar, and the second level of the navigation (the pages) is represented by an accordion.
-By default, the set of icons used are the [`filter` icons from the Google Material icons library](https://fonts.google.com/icons?icon.query=filter). The icon label ("Group A" and "Group B") appears as a tooltip on hovering over the icon.
+Here, the first level of the navigation hierarchy ("Group A" and "Group B") is represented by an icon in a navigation bar, and the second level of the navigation (the pages) is represented by an accordion. By default, the set of icons used are the [`filter` icons from the Google Material icons library](https://fonts.google.com/icons?icon.query=filter). The icon label ("Group A" and "Group B") appears as a tooltip on hovering over the icon.
## Customize the navigation bar
@@ -314,7 +304,6 @@ The same configuration for [grouping pages](#group-pages) applies inside a `NavL
```
=== "app.py"
-
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -375,10 +364,9 @@ The same configuration for [grouping pages](#group-pages) applies inside a `NavL
Group B:
- My third page
```
- === "Result"
- [![AccordionInsideNavBar]][AccordionInsideNavBar]
- [AccordionInsideNavBar]: ../../assets/user_guides/navigation/accordion_inside_nav_bar.png
+ === "Result"
+ [![AccordionInsideNavBar]][accordioninsidenavbar]
You can alter the icons used by specifying the name of the icon in the [Google Material icons library](https://fonts.google.com/icons):
@@ -402,8 +390,8 @@ You can alter the icons used by specifying the name of the icon in the [Google M
),
)
```
- === "app.py"
+ === "app.py"
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -468,7 +456,13 @@ You can alter the icons used by specifying the name of the icon in the [Google M
pages:
- My third page
```
- === "Result"
- [![CustomIcons]][CustomIcons]
- [CustomIcons]: ../../assets/user_guides/navigation/custom_icons.png
+ === "Result"
+ [![CustomIcons]][customicons]
+
+[accordioninsidenavbar]: ../../assets/user_guides/navigation/accordion_inside_nav_bar.png
+[customicons]: ../../assets/user_guides/navigation/custom_icons.png
+[defaultnavigation]: ../../assets/user_guides/navigation/default_navigation.png
+[groupednavigation]: ../../assets/user_guides/navigation/grouped_navigation.png
+[navbar]: ../../assets/user_guides/navigation/nav_bar.png
+[onlysomepages]: ../../assets/user_guides/navigation/only_some_pages.png
diff --git a/vizro-core/docs/pages/user-guides/pages.md b/vizro-core/docs/pages/user-guides/pages.md
index 7ae944e9b..71e01e9f9 100644
--- a/vizro-core/docs/pages/user-guides/pages.md
+++ b/vizro-core/docs/pages/user-guides/pages.md
@@ -1,7 +1,6 @@
# How to use pages
-This guide shows you how to add pages to your dashboard and customize the URL paths if needed.
-A [`Page`][vizro.models.Page] lets you place and arrange your dashboard content (for example, chart/components, tables, and text)
-and configure your dashboard interactions (such as filters and parameters).
+
+This guide shows you how to add pages to your dashboard and customize the URL paths if needed. A [`Page`][vizro.models.Page] lets you place and arrange your dashboard content (for example, chart/components, tables, and text) and configure your dashboard interactions (such as filters and parameters).
The [`Dashboard`][vizro.models.Dashboard] model accepts the `pages` argument, where you can insert your [`Page`][vizro.models.Page].
@@ -10,19 +9,19 @@ The [`Dashboard`][vizro.models.Dashboard] model accepts the `pages` argument, wh
A [`Page`][vizro.models.Page] is split up into four main containers:
1. The **navigation container** where you can customize your `navigation` (see [Dashboard](dashboard.md) and [Navigation](navigation.md) for more information). Note that the navigation container needs to be configured via the Dashboard.
-2. The **control container** where you can add your `controls` (see [Filters](filters.md) or [Parameters](parameters.md)) to interact with the dashboard
-3. The **page header** that contains the page title and the theme toggle switch button
-4. The **component container** where you can add your [components](components.md) to visualize your data
+1. The **control container** where you can add your `controls` (see [Filters](filters.md) or [Parameters](parameters.md)) to interact with the dashboard
+1. The **page header** that contains the page title and the theme toggle switch button
+1. The **component container** where you can add your [components](components.md) to visualize your data
To create and add a page to your dashboard, do the following steps:
1. Set a `title` for your [`Page`][vizro.models.Page]
-2. Configure your `components`, see our guide on the [various options](components.md)
-3. (optional) Configure your `controls` , see our guides on [Filters](filters.md) and [Parameters](parameters.md)
-4. (optional) Configure your `layout` , see our guide on [Layouts](layouts.md)
-5. (optional) Give a `description` of your `Page` to the app's [meta tags](https://metatags.io/)
+1. Configure your `components`, see our guide on the [various options](components.md)
+1. (optional) Configure your `controls` , see our guides on [Filters](filters.md) and [Parameters](parameters.md)
+1. (optional) Configure your `layout` , see our guide on [Layouts](layouts.md)
+1. (optional) Give a `description` of your `Page` to the app's [meta tags](https://metatags.io/)
!!! example "Page"
=== "app.py"
@@ -51,51 +50,47 @@ To create and add a page to your dashboard, do the following steps:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: sunburst
- path: ['continent', 'country']
- values: pop
- color: lifeExp
- data_frame: gapminder
- id: sunburst
- type: graph
- controls:
- - column: continent
- targets:
- - sunburst
- type: filter
- - selector:
- options: ['lifeExp', 'pop']
- title: Color
- type: radio_items
- targets:
- - sunburst.color
- type: parameter
- title: Page Title
- description: "Longer description of the page content"
+ - components:
+ - figure:
+ _target_: sunburst
+ path: [continent, country]
+ values: pop
+ color: lifeExp
+ data_frame: gapminder
+ id: sunburst
+ type: graph
+ controls:
+ - column: continent
+ targets: [sunburst]
+ type: filter
+ - selector:
+ options: [lifeExp, pop]
+ title: Color
+ type: radio_items
+ targets: [sunburst.color]
+ type: parameter
+ title: Page Title
+ description: Longer description of the page content
```
- === "Result"
- [![Page]][Page]
- [Page]: ../../assets/user_guides/pages/page_sunburst.png
+ === "Result"
+ [![Page]][page]
An accordion page selector is automatically added to your dashboard in the top-left of the control container for through the different pages. It will not be added if your dashboard consists of only one page.
You can additionally navigate through the different pages by going directly to the relevant page URL (more details in next section).
-
## Customize the page URL
-By default, the page URL is automatically generated based on the `id` of the page. For example, if `id="This is my first page"`
-the generated page URL will be `path=this-is-my-first-page`. You can then access the page via `localhost:/this-is-my-first-page`.
-Note that the page `id` defaults to be the same as the page `title` if not set.
-If you have multiple pages with the same `title` then you must assign a unique `id`.
+By default, the page URL is automatically generated based on the `id` of the page. For example, if `id="This is my first page"` the generated page URL will be `path=this-is-my-first-page`. You can then access the page via `localhost:/this-is-my-first-page`.
+
+Note that the page `id` defaults to be the same as the page `title` if not set. If you have multiple pages with the same `title` then you must assign a unique `id`.
The first page always has the URL prefix `/` assigned. A custom URL can, therefore, not be created for the first page.
@@ -137,39 +132,40 @@ To customize the page URL, pass a valid URL name to the `path` argument of [`Pag
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- Commodi repudiandae consequuntur voluptatum.
- type: card
- title: Page 1
- - components:
- - figure:
- _target_: sunburst
- path: ['continent', 'country']
- values: pop
- color: lifeExp
- data_frame: gapminder
- id: sunburst
- type: graph
- controls:
- - column: continent
- targets:
- - sunburst
- type: filter
- - selector:
- options: ['lifeExp', 'pop']
- title: Color
- type: radio_items
- targets:
- - sunburst.color
- type: parameter
- title: Page 2
- path: my-custom-url
+ - components:
+ - text: |
+ Commodi repudiandae consequuntur voluptatum.
+ type: card
+ title: Page 1
+ - components:
+ - figure:
+ _target_: sunburst
+ path: [continent, country]
+ values: pop
+ color: lifeExp
+ data_frame: gapminder
+ id: sunburst
+ type: graph
+ controls:
+ - column: continent
+ targets: [sunburst]
+ type: filter
+ - selector:
+ options: [lifeExp, pop]
+ title: Color
+ type: radio_items
+ targets: [sunburst.color]
+ type: parameter
+ title: Page 2
+ path: my-custom-url
```
You can now access the first page via `localhost:/` and the second page via `localhost:/my-custom-url`.
+
+[page]: ../../assets/user_guides/pages/page_sunburst.png
diff --git a/vizro-core/docs/pages/user-guides/parameters.md b/vizro-core/docs/pages/user-guides/parameters.md
index bb39a7a0c..c82707d4a 100644
--- a/vizro-core/docs/pages/user-guides/parameters.md
+++ b/vizro-core/docs/pages/user-guides/parameters.md
@@ -9,8 +9,8 @@ The [`Page`][vizro.models.Page] model accepts the `controls` argument, where you
To add a parameter to your page, do the following:
1. add the [`Parameter`][vizro.models.Parameter] model into the `controls` argument of the [`Page`][vizro.models.Page] model.
-2. add the `targets` argument
-3. add a selector model to the `selector` argument.
+1. add the `targets` argument
+1. add a selector model to the `selector` argument.
In the `targets` argument, you can specify the component and function argument that the parameter should be applied to in the form of `.` (for example, `scatter_chart.title`).
@@ -48,6 +48,7 @@ Unlike for the [`Filter`][vizro.models.Filter] model, you also have to configure
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -64,18 +65,17 @@ Unlike for the [`Filter`][vizro.models.Filter] model, you also have to configure
type: graph
controls:
- selector:
- options: ["My scatter chart", "A better title!", "Another title..."]
- multi: False
+ options: [My scatter chart, A better title!, Another title...]
+ multi: false
type: dropdown
targets:
- scatter_chart.title
type: parameter
title: My first page
```
- === "Result"
- [![Parameter]][Parameter]
- [Parameter]: ../../assets/user_guides/control/control4.png
+ === "Result"
+ [![Parameter]][parameter]
If you would like to pass `None` as a parameter and make a parameter optional, you can specify the string `"NONE"` in the `options` or `value` field.
@@ -133,6 +133,7 @@ If you want to change nested parameters, you can specify the `targets` argument
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -146,7 +147,7 @@ If you want to change nested parameters, you can specify the `targets` argument
y: sepal_length
size: petal_length
color: species
- color_discrete_map: {"setosa": "#00b4ff", "versicolor": "#ff9222"}
+ color_discrete_map: {setosa: '#00b4ff', versicolor: '#ff9222'}
id: scatter_chart
type: graph
- figure:
@@ -155,23 +156,22 @@ If you want to change nested parameters, you can specify the `targets` argument
x: sepal_width
y: sepal_length
color: species
- color_discrete_map: {"setosa": "#00b4ff", "versicolor": "#ff9222"}
+ color_discrete_map: {setosa: '#00b4ff', versicolor: '#ff9222'}
id: bar_chart
type: graph
controls:
- selector:
- options: ["#ff5267", "#3949ab"]
+ options: ['#ff5267', '#3949ab']
value: #3949ab
- multi: False
+ multi: false
type: dropdown
- targets: ["scatter_chart.color_discrete_map.virginica", "bar_chart.color_discrete_map.virginica"]
+ targets: [scatter_chart.color_discrete_map.virginica, bar_chart.color_discrete_map.virginica]
type: parameter
title: My first page
```
- === "Result"
- [![Nested]][Nested]
- [Nested]: ../../assets/user_guides/control/control5.png
+ === "Result"
+ [![Nested]][nested]
In the above example, the object passed to the function argument `color_discrete_map` is a dictionary which maps the different flower species to fixed colors (for example, `{"virginica":"blue"}`). In this case, only the value `blue` should be changed instead of the entire dictionary. This can be achieved by specifying a target as `scatter.color_discrete_map.virginica`.
@@ -180,3 +180,6 @@ Note that in the above example, one parameter affects multiple targets.
## Dynamic data parameters
If you use [dynamic data](data.md/#dynamic-data) that can be updated while the dashboard is running then you can pass parameters to the dynamic data function to alter the data loaded into your dashboard. For detailed instructions, refer to the section on [parametrized data loading](data.md/#parametrize-data-loading).
+
+[nested]: ../../assets/user_guides/control/control5.png
+[parameter]: ../../assets/user_guides/control/control4.png
diff --git a/vizro-core/docs/pages/user-guides/run.md b/vizro-core/docs/pages/user-guides/run.md
index df52e8c14..028eb5027 100644
--- a/vizro-core/docs/pages/user-guides/run.md
+++ b/vizro-core/docs/pages/user-guides/run.md
@@ -15,7 +15,6 @@ Most of our examples have a link below the code, [Run and edit this code in PyCa
You can use [PyCafe](https://py.cafe/snippet/vizro/v1) snippet mode to experiment with your own Vizro dashboards by dropping code into a new project.
-
## Default built-in Flask development server
!!! example "Default built-in Flask development server"
@@ -38,9 +37,10 @@ You can use [PyCafe](https://py.cafe/snippet/vizro/v1) snippet mode to experimen
Vizro().build(dashboard).run()
```
+
1. create a Python file named `app.py`.
-2. type the command `python app.py` into your terminal.
-3. information below will be displayed in your terminal, go to [http://127.0.0.1:8050/](http://127.0.0.1:8050/).
+1. type the command `python app.py` into your terminal.
+1. information below will be displayed in your terminal, go to [http://127.0.0.1:8050/](http://127.0.0.1:8050/).
```
Dash is running on http://127.0.0.1:8050/
@@ -51,8 +51,7 @@ INFO:werkzeug:WARNING: This is a development server. Do not use it in a producti
```
!!! warning "In production"
-
- As per the above warning message, which is [further explained in the Flask documentation](https://flask.palletsprojects.com/en/3.0.x/deploying/), the Flask development server is intended for use only during local development and **should not** be used when deploying to production. Instead, you should instead use a production-ready solution such as [Gunicorn](#gunicorn).
+ The above warning message is [further explained in the Flask documentation](https://flask.palletsprojects.com/en/3.0.x/deploying/). The Flask development server is intended for use only during local development and **should not** be used when deploying to production. Instead, you should instead use a production-ready solution such as [Gunicorn](#gunicorn).
### Automatic reloading and debugging
@@ -64,11 +63,11 @@ Setting `debug=True` enables [Dash Dev Tools](https://dash.plotly.com/devtools).
In addition, some errors generated at run time can also be viewed via the browser console (for example in `Chrome` see `View > Developer > Developer Tools > Console`).
-
## Jupyter
+
The dashboard application can be launched in a Jupyter environment in `inline`, `external`, and `jupyterlab` mode.
-!!! example "Run in a Jupyter Notebook in inline mode"
+!!! example "Run in a Jupyter Notebook in inline mode"
=== "app.ipynb"
```py linenums="1"
from vizro import Vizro
@@ -87,16 +86,16 @@ The dashboard application can be launched in a Jupyter environment in `inline`,
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run(jupyter_mode="external")
```
+
- by default, the mode is set to `inline` in `run()` and the dashboard will be displayed inside your Jupyter environment.
- you can specify `jupyter_mode="external"` and a link will be displayed to direct you to the localhost where the dashboard is running.
- you can use tab mode by `jupyter_mode="tab"` to automatically open the app in a new browser
!!! note "Reloading and debugging"
-
Code reloading and hot reloading do not work within a Jupyter Notebook. Instead, there are two methods to reload the dashboard:
- * Restart the Jupyter kernel and re-run your notebook.
- * Add a cell containing `from vizro import Vizro; Vizro._reset()` to the top of your notebook and re-run it. With this method, there is no need to restart the Jupyter kernel.
+ - Restart the Jupyter kernel and re-run your notebook.
+ - Add a cell containing `from vizro import Vizro; Vizro._reset()` to the top of your notebook and re-run it. With this method, there is no need to restart the Jupyter kernel.
## Gunicorn
@@ -126,17 +125,18 @@ The dashboard application can be launched in a Jupyter environment in `inline`,
```
1. The Vizro `app` object is a WSGI application that exposes the underlying Flask app; this will be used by Gunicorn.
- 2. Enable the same app to still be run using the built-in Flask server with `python app.py` for development purposes.
+ 1. Enable the same app to still be run using the built-in Flask server with `python app.py` for development purposes.
To run using Gunicorn with four worker processes, execute
+
```bash
gunicorn app:app --workers 4
```
+
in the command line. For more Gunicorn configuration options, refer to [Gunicorn documentation](https://docs.gunicorn.org/).
!!! warning "In production"
-
- If your dashboard uses [dynamic data](data.md#dynamic-data) that can be refreshed while the dashboard is running then you should [configure your data manager cache](data.md#configure-cache) to use a backend that supports multiple processes.
+ If your dashboard uses [dynamic data](data.md#dynamic-data) that can be refreshed while the dashboard is running then you should [configure your data manager cache](data.md#configure-cache) to use a back end that supports multiple processes.
## Deployment
@@ -149,6 +149,6 @@ Internally, `app = Vizro()` contains a Flask app in `app.dash.server`. However,
[`Vizro`][vizro.Vizro] accepts `**kwargs` that are passed through to `Dash`. This enables you to configure the underlying Dash app using the same [arguments that are available](https://dash.plotly.com/reference#dash.dash) in `Dash`. For example, in a deployment context, these arguments may be useful:
-- `url_base_pathname`: serve your Vizro app at a specific path rather than at the domain root. For example, if you host your dashboard at http://www.example.com/my_dashboard/ then you would set `url_base_pathname="/my_dashboard/"` or an environment variable `DASH_URL_BASE_PATHNAME="/my_dashboard/"`.
+- `url_base_pathname`: serve your Vizro app at a specific path rather than at the domain root. For example, if you host your dashboard at `http://www.example.com/my_dashboard/` then you would set `url_base_pathname="/my_dashboard/"` or an environment variable `DASH_URL_BASE_PATHNAME="/my_dashboard/"`.
- `serve_locally`: set to `False` to [serve Dash component libraries from a Content Delivery Network (CDN)](https://dash.plotly.com/external-resources#serving-dash's-component-libraries-locally-or-from-a-cdn), which reduces load on the server and can improve performance. Vizro uses [jsDeliver](https://www.jsdelivr.com/) as a CDN for CSS and JavaScript sources.
- `assets_external_path`: when `serve_locally=False`, you can also set `assets_external_path` or an environment variable `DASH_ASSETS_EXTERNAL_PATH` to [serve your own assets from a CDN](https://dash.plotly.com/external-resources#load-assets-from-a-folder-hosted-on-a-cdn).
diff --git a/vizro-core/docs/pages/user-guides/selectors.md b/vizro-core/docs/pages/user-guides/selectors.md
index 10481d2ba..a1bd4be20 100644
--- a/vizro-core/docs/pages/user-guides/selectors.md
+++ b/vizro-core/docs/pages/user-guides/selectors.md
@@ -6,10 +6,7 @@ The [`Filter`][vizro.models.Filter] or the [`Parameter`][vizro.models.Parameter]
## Categorical selectors
-Within the categorical selectors, a clear distinction exists between multi-option and single-option selectors.
-For instance, the [`Checklist`][vizro.models.Checklist] functions as a multi-option selector by default while
-the [`RadioItem`][vizro.models.RadioItems] serves as a single-option selector by default. However, the
-[`Dropdown`][vizro.models.Dropdown] can function as both a multi-option or single-option selector.
+Within the categorical selectors, a clear distinction exists between multi-option and single-option selectors. For instance, the [`Checklist`][vizro.models.Checklist] functions as a multi-option selector by default while the [`RadioItem`][vizro.models.RadioItems] serves as a single-option selector by default. However, the [`Dropdown`][vizro.models.Dropdown] can function as both a multi-option or single-option selector.
For more information, refer to the API reference of the selector, or the documentation of its underlying Dash component:
@@ -18,15 +15,12 @@ For more information, refer to the API reference of the selector, or the documen
- [`RadioItems`][vizro.models.RadioItems] based on [`dcc.RadioItems`](https://dash.plotly.com/dash-core-components/radioitems)
!!! note
-
- When configuring the `options` of the categorical selectors, you can either provide:
+ When configuring the `options` of the categorical selectors, you can either give:
- a list of values `options = ['Value A', 'Value B', 'Value C']`
- or a dictionary of label-value mappings `options=[{'label': 'True', 'value': True}, {'label': 'False', 'value': False}]`
- The later is required if you want to provide different display labels to your option values or in case you want to
- provide boolean values as options. In this case, you need to provide a string label for your boolean values as
- boolean values cannot be displayed properly as labels in the underlying Dash components.
+ The later is required if you want to provide different display labels to your option values or in case you want to provide boolean values as options. In this case, you need to provide a string label for your boolean values as boolean values cannot be displayed properly as labels in the underlying Dash components.
## Numerical selectors
@@ -36,11 +30,7 @@ For more information, refer to the API reference of the selector, or the documen
- [`RangeSlider`][vizro.models.RangeSlider] based on [`dcc.RangeSlider`](https://dash.plotly.com/dash-core-components/rangeslider)
!!! note
-
- When configuring the [`Slider`][vizro.models.Slider] and the [`RangeSlider`][vizro.models.RangeSlider] with float values, and using `step` with an integer value, you may notice
- unexpected behavior, such as the drag value being outside its indicated marks.
- To our knowledge, this is a current bug in the underlying [`dcc.Slider`](https://dash.plotly.com/dash-core-components/slider) and
- [`dcc.RangeSlider`](https://dash.plotly.com/dash-core-components/rangeslider) component, which you can circumvent by adapting the `step` size accordingly.
+ When configuring the [`Slider`][vizro.models.Slider] and the [`RangeSlider`][vizro.models.RangeSlider] with float values, and using `step` with an integer value, you may notice unexpected behavior, such as the drag value being outside its indicated marks. To our knowledge, this is a current bug in the underlying [`dcc.Slider`](https://dash.plotly.com/dash-core-components/slider) and [`dcc.RangeSlider`](https://dash.plotly.com/dash-core-components/rangeslider) component, which you can circumvent by adapting the `step` size as needed.
## Temporal selectors
@@ -49,7 +39,6 @@ For more information, refer to the API reference of the selector, or the documen
- [`DatePicker`][vizro.models.DatePicker] based on [`dmc.DateRangePicker`](https://www.dash-mantine-components.com/components/datepicker#daterangepicker) and [`dmc.DatePicker`](https://www.dash-mantine-components.com/components/datepicker)
!!! note
-
When the [`DatePicker`][vizro.models.DatePicker] is configured with `range=True` (the default), the underlying component is `dmc.DateRangePicker`. When `range=False` the underlying component is `dmc.DatePicker`.
When configuring the [`DatePicker`][vizro.models.DatePicker] make sure to provide your dates for `min`, `max` and `value` arguments in `"yyyy-mm-dd"` format or as `datetime` type (for example, `datetime.datetime(2024, 01, 01)`).
diff --git a/vizro-core/docs/pages/user-guides/table.md b/vizro-core/docs/pages/user-guides/table.md
index 19197c465..80e8e53dc 100755
--- a/vizro-core/docs/pages/user-guides/table.md
+++ b/vizro-core/docs/pages/user-guides/table.md
@@ -2,46 +2,32 @@
This guide shows you how to visualize tables in Vizro.
-There are two ways to visualize tables in Vizro, using either [AG Grid](#ag-grid) or [Dash DataTable](#dash-datatable).
-In general, [AG Grid](#ag-grid) is Vizro's recommended table implementation, but sometimes it may make sense to use the [Dash DataTable](#dash-datatable) instead.
+There are two ways to visualize tables in Vizro, using either [AG Grid](#ag-grid) or [Dash DataTable](#dash-datatable). In general, [AG Grid](#ag-grid) is Vizro's recommended table implementation, but sometimes it may make sense to use the [Dash DataTable](#dash-datatable) instead.
## Choose between AG Grid and Dash DataTable
-Vizro offers two models - the [`AgGrid`][vizro.models.AgGrid] model and the [`Table`][vizro.models.Table] model - for the above two approaches respectively.
-They both visualize tabular data in similar ways.
+Vizro offers two models - the [`AgGrid`][vizro.models.AgGrid] model and the [`Table`][vizro.models.Table] model - for the above two approaches respectively. They both visualize tabular data in similar ways.
-The main difference between the two is that the [`AgGrid`][vizro.models.AgGrid] model is based on Plotly's [Dash AG Grid](https://dash.plotly.com/dash-ag-grid) component,
-while the [`Table`][vizro.models.Table] model is based on the [Dash DataTable](https://dash.plotly.com/datatable) component.
-
-Both approaches have similar base features, and are configurable in similar ways. However, the AG Grid offers more advanced features out-of-the-box, is more customizable
-and also ships a powerful enterprise version. This is why it is Vizro's recommended table implementation. At the same time, the Dash DataTable can be used if developers are
-already familiar with it, or if some custom functionality is easier to implement using the Dash DataTable.
+The main difference between the two is that the [`AgGrid`][vizro.models.AgGrid] model is based on Plotly's [Dash AG Grid](https://dash.plotly.com/dash-ag-grid) component, while the [`Table`][vizro.models.Table] model is based on the [Dash DataTable](https://dash.plotly.com/datatable) component.
+Both approaches have similar base features, and are configurable in similar ways. However, the AG Grid offers more advanced features out-of-the-box, is more customizable and also ships a powerful enterprise version. This is why it is Vizro's recommended table implementation. At the same time, the Dash DataTable can be used if developers are already familiar with it, or if some custom functionality is easier to implement using the Dash DataTable.
## AG Grid
-[AG Grid](https://www.ag-grid.com/) is an interactive table/grid component designed for viewing, editing, and exploring large datasets. It
-is Vizro's recommended table implementation.
+[AG Grid](https://www.ag-grid.com/) is an interactive table/grid component designed for viewing, editing, and exploring large datasets. It is Vizro's recommended table implementation.
-The Vizro [`AgGrid`][vizro.models.AgGrid] model is based on the [Dash AG Grid](https://dash.plotly.com/dash-ag-grid), which is in turn based the
-original [Javascript implementation](https://www.ag-grid.com/).
+The Vizro [`AgGrid`][vizro.models.AgGrid] model is based on the [Dash AG Grid](https://dash.plotly.com/dash-ag-grid), which is in turn based the original [Javascript implementation](https://www.ag-grid.com/).
### Basic usage
To add a [`AgGrid`][vizro.models.AgGrid] to your page, do the following:
-1. Insert the [`AgGrid`][vizro.models.AgGrid] model into the `components` argument of the
-[`Page`][vizro.models.Page] model.
-2. Enter the `dash_ag_grid` function under the `figure` argument (imported via `from vizro.tables import dash_ag_grid`).
-
-The Vizro version of this AG Grid differs in one way from the original Dash AG Grid: it requires the user to pass a pandas DataFrame as the source of data.
-As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`. Most other [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments.
-Note that some defaults are set for some arguments (for example, for `columnDefs`) to help with styling and usability.
-Sometimes a parameter may not work because it requires a callback to function. In that case you can try [creating a custom AG Grid callable](custom-tables.md).
+1. Insert the [`AgGrid`][vizro.models.AgGrid] model into the `components` argument of the [`Page`][vizro.models.Page] model.
+1. Enter the `dash_ag_grid` function under the `figure` argument (imported via `from vizro.tables import dash_ag_grid`).
+The Vizro version of this AG Grid differs in one way from the original Dash AG Grid: it requires the user to pass a pandas DataFrame as the source of data. As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`. Most other [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments. Note that some defaults are set for some arguments (for example, for `columnDefs`) to help with styling and usability. Sometimes a parameter may not work because it requires a callback to function. In that case you can try [creating a custom AG Grid callable](custom-tables.md).
!!! example "Basic Dash AG Grid"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -59,29 +45,28 @@ Sometimes a parameter may not work because it requires a callback to function. I
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - figure:
- _target_: dash_ag_grid
- data_frame: gapminder
- type: ag_grid
- title: Default Dash AG Grid
+ - components:
+ - figure:
+ _target_: dash_ag_grid
+ data_frame: gapminder
+ type: ag_grid
+ title: Default Dash AG Grid
```
- === "Result"
- [![AGGrid]][AGGrid]
- [AGGrid]: ../../assets/user_guides/table/aggrid.png
+ === "Result"
+ [![AGGrid]][aggrid]
### Enable pagination
-Pagination is a visual alternative to using vertical scroll. It can also improve loading time if you have many rows.
-You can turn it on by setting `dashGridOptions={"pagination": True}`.
-!!! example "Basic Dash AG Grid"
+Pagination is a visual alternative to using vertical scroll. It can also improve loading time if you have many rows. You can turn it on by setting `dashGridOptions={"pagination": True}`.
+!!! example "Basic Dash AG Grid"
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -99,37 +84,34 @@ You can turn it on by setting `dashGridOptions={"pagination": True}`.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - figure:
- _target_: dash_ag_grid
- data_frame: gapminder
- dashGridOptions:
- pagination: true
- type: ag_grid
- title: Dash AG Grid with pagination
+ - components:
+ - figure:
+ _target_: dash_ag_grid
+ data_frame: gapminder
+ dashGridOptions:
+ pagination: true
+ type: ag_grid
+ title: Dash AG Grid with pagination
```
- === "Result"
- [![AGGrid]][AGGrid]
- [AGGrid]: ../../assets/user_guides/table/aggrid-pagination.png
+ === "Result"
+ [![AGGrid]][aggrid]
### Formatting columns
#### Numbers
-One of the most common tasks when working with tables is to format the columns so that displayed numbers are more readable.
-To do this, you can use the native functionality of [value formatters](https://dash.plotly.com/dash-ag-grid/value-formatters)
-or the Vizro pre-defined [custom cell data types](https://dash.plotly.com/dash-ag-grid/cell-data-types#providing-custom-cell-data-types) as shown below.
+One of the most common tasks when working with tables is to format the columns so that displayed numbers are more readable. To do this, you can use the native functionality of [value formatters](https://dash.plotly.com/dash-ag-grid/value-formatters) or the Vizro pre-defined [custom cell data types](https://dash.plotly.com/dash-ag-grid/cell-data-types#providing-custom-cell-data-types) as shown below.
The available custom cell types for Vizro are `dollar`, `euro`, `percent` and `numeric`.
-To use these, define your desired `` alongside the chosen `cellDataType` in
-the `columnDefs` argument of your `dash_ag_grid` function:
+To use these, define your desired `` alongside the chosen `cellDataType` in the `columnDefs` argument of your `dash_ag_grid` function:
```py
columnDefs = [{"field": "", "cellDataType": "euro"}]
@@ -138,7 +120,6 @@ columnDefs = [{"field": "", "cellDataType": "euro"}]
In the example below we select and format some columns of the gapminder data.
!!! example "AG Grid with formatted columns"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -168,6 +149,7 @@ In the example below we select and format some columns of the gapminder data.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -190,33 +172,23 @@ In the example below we select and format some columns of the gapminder data.
type: ag_grid
title: Example of AG Grid with formatted columns
```
- === "Result"
- [![AGGrid2]][AGGrid2]
- [AGGrid2]: ../../assets/user_guides/table/formatted_aggrid.png
+ === "Result"
+ [![AGGrid2]][aggrid2]
#### Dates
-For the [`AgGrid`][vizro.models.AgGrid] model to sort and filter dates correctly, the date must either be of
-string format `yyyy-mm-dd` (see [Dash AG Grid docs](https://dash.plotly.com/dash-ag-grid/date-filters#example:-date-filter))
-or a pandas datetime object. Any pandas datetime column will be transformed into the `yyyy-mm-dd` format automatically.
+For the [`AgGrid`][vizro.models.AgGrid] model to sort and filter dates correctly, the date must either be of string format `yyyy-mm-dd` (see [Dash AG Grid docs](https://dash.plotly.com/dash-ag-grid/date-filters#example:-date-filter)) or a pandas datetime object. Any pandas datetime column will be transformed into the `yyyy-mm-dd` format automatically.
#### Objects and strings
-No specific formatting is available for custom objects and strings, however you can make use of [Value Formatters](https://dash.plotly.com/dash-ag-grid/value-formatters)
-to format displayed strings automatically.
-
+No specific formatting is available for custom objects and strings, however you can make use of [Value Formatters](https://dash.plotly.com/dash-ag-grid/value-formatters) to format displayed strings automatically.
### Styling and changing the AG Grid
-As mentioned above, all [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments. Below you can find
-an example of a styled AG Grid where some conditional formatting is applied, and where the columns are editable, but
-not filterable or resizable. There are more ways to alter the grid beyond this showcase. AG Grid, like any other Vizro
-component, can be customized using custom CSS. You can find information in
-the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-selected-components).
+As mentioned above, all [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments. Below you can find an example of a styled AG Grid where some conditional formatting is applied, and where the columns are editable, but not filterable or resizable. There are more ways to alter the grid beyond this showcase. AG Grid, like any other Vizro component, can be customized using custom CSS. You can find information in the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-selected-components).
!!! example "Styled and modified Dash AG Grid"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -284,6 +256,7 @@ the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-select
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -299,28 +272,28 @@ the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-select
- field: year
- field: lifeExp
valueFormatter:
- function: "d3.format('.1f')(params.value)"
+ function: d3.format('.1f')(params.value)
- field: gdpPercap
valueFormatter:
- function: "d3.format('$,.1f')(params.value)"
+ function: d3.format('$,.1f')(params.value)
cellStyle:
styleConditions:
- condition: params.value < 1045
style:
- backgroundColor: "#ff9222"
+ backgroundColor: '#ff9222'
- condition: params.value >= 1045 && params.value <= 4095
style:
- backgroundColor: "#de9e75"
+ backgroundColor: '#de9e75'
- condition: params.value > 4095 && params.value <= 12695
style:
- backgroundColor: "#aaa9ba"
+ backgroundColor: '#aaa9ba'
- condition: params.value > 12695
style:
- backgroundColor: "#00b4ff"
+ backgroundColor: '#00b4ff'
- field: pop
type: rightAligned
valueFormatter:
- function: "d3.format(',.0f')(params.value)"
+ function: d3.format(',.0f')(params.value)
defaultColDef:
resizable: false
filter: false
@@ -329,10 +302,9 @@ the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-select
type: ag_grid
title: Example of a Dash AG Grid
```
- === "Result"
- [![AGGrid3]][AGGrid3]
- [AGGrid3]: ../../assets/user_guides/table/styled_aggrid.png
+ === "Result"
+ [![AGGrid3]][aggrid3]
If the available arguments are not sufficient, there is always the option to [create a custom AG Grid callable](custom-tables.md).
@@ -348,19 +320,14 @@ The Vizro [`Table`][vizro.models.Table] model is based on the [Dash DataTable](h
To add a [`Table`][vizro.models.Table] to your page, do the following:
-1. Insert the [`Table`][vizro.models.Table] model into the `components` argument of the
-[`Page`][vizro.models.Page] model.
-2. Enter the `dash_data_table` function under the `figure` argument (imported via `from vizro.tables import dash_data_table`).
-
+1. Insert the [`Table`][vizro.models.Table] model into the `components` argument of the [`Page`][vizro.models.Page] model.
+1. Enter the `dash_data_table` function under the `figure` argument (imported via `from vizro.tables import dash_data_table`).
-The Vizro version of this table differs in one way from the original table: it requires the user to pass a pandas DataFrame as the source of data.
-As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`.
+The Vizro version of this table differs in one way from the original table: it requires the user to pass a pandas DataFrame as the source of data. As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`.
-All other [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Note that we are
-setting some defaults for some arguments to help with styling.
+All other [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Note that we are setting some defaults for some arguments to help with styling.
!!! example "Dash DataTable"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -380,31 +347,29 @@ setting some defaults for some arguments to help with styling.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: dash_data_table
- data_frame: gapminder_2007
- title: Dash DataTable
- type: table
- title: Example of a Dash DataTable
+ - components:
+ - figure:
+ _target_: dash_data_table
+ data_frame: gapminder_2007
+ title: Dash DataTable
+ type: table
+ title: Example of a Dash DataTable
```
- === "Result"
- [![Table]][Table]
- [Table]: ../../assets/user_guides/table/table.png
+ === "Result"
+ [![Table]][table]
### Styling and changing the Dash DataTable
-As mentioned above, all [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Below you can find
-an example of a styled table where some conditional formatting is applied. There are many more ways to alter the table beyond this showcase.
+As mentioned above, all [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Below you can find an example of a styled table where some conditional formatting is applied. There are many more ways to alter the table beyond this showcase.
!!! example "Styled Dash DataTable"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -467,6 +432,7 @@ an example of a styled table where some conditional formatting is applied. There
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -504,12 +470,12 @@ an example of a styled table where some conditional formatting is applied. There
backgroundColor: dodgerblue
color: white
- if:
- filter_query: "{lifeExp} < 55"
+ filter_query: '{lifeExp} < 55'
column_id: lifeExp
- backgroundColor: "#85144b"
+ backgroundColor: '#85144b'
color: white
- if:
- filter_query: "{gdpPercap} > 10000"
+ filter_query: '{gdpPercap} > 10000'
column_id: gdpPercap
backgroundColor: green
color: white
@@ -524,26 +490,20 @@ an example of a styled table where some conditional formatting is applied. There
title: Dash DataTable
```
- === "Result"
- [![Table2]][Table2]
- [Table2]: ../../assets/user_guides/table/styled_table.png
+ === "Result"
+ [![Table2]][table2]
If the available arguments are not sufficient, there is always the option to create a [custom Dash DataTable](custom-tables.md).
-
## Add title, header, and footer
-The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] models accept a `title`, `header` and
-`footer` argument. This is useful for providing context to the data being displayed, or for adding a description of
-the data.
+The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] models accept a `title`, `header` and `footer` argument. This is useful for providing context to the data being displayed, or for adding a description of the data.
- **title**: Displayed as an [H3 header](https://dash.plotly.com/dash-html-components/h3), useful for summarizing the main topic or insight of the component.
- **header**: Accepts markdown text, ideal for extra descriptions, subtitles, or detailed data insights.
- **footer**: Accepts markdown text, commonly used for citing data sources, providing information on the last update, or adding disclaimers.
-
-
### Formatted AgGrid
!!! example "Formatted AgGrid"
@@ -571,30 +531,29 @@ the data.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: dash_ag_grid
- data_frame: gapminder_2007
- dashGridOptions:
- pagination: true
- title: Gapminder Data Insights
- header: |
- #### An Interactive Exploration of Global Health, Wealth, and Population
- footer: |
- SOURCE: **Plotly gapminder data set, 2024**
- type: ag_grid
- title: Formatted AgGrid
+ - components:
+ - figure:
+ _target_: dash_ag_grid
+ data_frame: gapminder_2007
+ dashGridOptions:
+ pagination: true
+ title: Gapminder Data Insights
+ header: |
+ #### An Interactive Exploration of Global Health, Wealth, and Population
+ footer: |
+ SOURCE: **Plotly gapminder data set, 2024**
+ type: ag_grid
+ title: Formatted AgGrid
```
- === "Result"
- [![FormattedGrid]][FormattedGrid]
-
- [FormattedGrid]: ../../assets/user_guides/components/formatted_aggrid.png
+ === "Result"
+ [![FormattedGrid]][formattedgrid]
### Formatted DataTable
@@ -623,24 +582,32 @@ the data.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: dash_data_table
- data_frame: gapminder_2007
- title: Gapminder Data Insights
- header: |
- #### An Interactive Exploration of Global Health, Wealth, and Population
- footer: |
- SOURCE: **Plotly gapminder data set, 2024**
- type: table
- title: Formatted DataTable
+ - components:
+ - figure:
+ _target_: dash_data_table
+ data_frame: gapminder_2007
+ title: Gapminder Data Insights
+ header: |
+ #### An Interactive Exploration of Global Health, Wealth, and Population
+ footer: |
+ SOURCE: **Plotly gapminder data set, 2024**
+ type: table
+ title: Formatted DataTable
```
- === "Result"
- [![FormattedTable]][FormattedTable]
- [FormattedTable]: ../../assets/user_guides/components/formatted_table.png
+ === "Result"
+ [![FormattedTable]][formattedtable]
+
+[aggrid]: ../../assets/user_guides/table/aggrid.png
+[aggrid2]: ../../assets/user_guides/table/formatted_aggrid.png
+[aggrid3]: ../../assets/user_guides/table/styled_aggrid.png
+[formattedgrid]: ../../assets/user_guides/components/formatted_aggrid.png
+[formattedtable]: ../../assets/user_guides/components/formatted_table.png
+[table]: ../../assets/user_guides/table/table.png
+[table2]: ../../assets/user_guides/table/styled_table.png
diff --git a/vizro-core/docs/pages/user-guides/tabs.md b/vizro-core/docs/pages/user-guides/tabs.md
index 09154177e..1811d0cac 100755
--- a/vizro-core/docs/pages/user-guides/tabs.md
+++ b/vizro-core/docs/pages/user-guides/tabs.md
@@ -1,8 +1,6 @@
# How to use tabs
-[`Tabs`][vizro.models.Tabs] organize and separate groups of related content in a dashboard, letting users switch between different sections or views.
-They are essentially a way of putting multiple [`Containers`][vizro.models.Container] in the same screen space, and letting the user switch between them.
-`Containers` enable the grouping of page components into sections and subsections. See our [user guide on `Containers`](container.md) for more information.
+[`Tabs`][vizro.models.Tabs] organize and separate groups of related content in a dashboard, letting users switch between different sections or views. They are essentially a way of putting multiple [`Containers`][vizro.models.Container] in the same screen space, and letting the user switch between them. `Containers` enable the grouping of page components into sections and subsections. See our [user guide on `Containers`](container.md) for more information.
{ width="400"}
@@ -16,14 +14,12 @@ This guide shows you how to use tabs to organize your `Containers` into subsecti
By using [`Tabs`][vizro.models.Tabs], the following applies:
- [`Filters`][vizro.models.Filter] affect all components on all tabs (opened and closed) of the page if not specified otherwise inside `Filter.targets`
-- The `title` of the [`Container`][vizro.models.Container] inserted into `Tabs.tabs` will be displayed as a tab label, and the title will be removed from the `Container`
-
+- The `title` of the [`Container`][vizro.models.Container] inserted into `Tabs.tabs` will be displayed as a tab label, and the title will be removed from the `Container`
To add [`Tabs`][vizro.models.Tabs] to your page, do the following:
1. Insert the [`Tabs`][vizro.models.Tabs] into the `components` argument of the [`Page`][vizro.models.Page]
-2. Insert your [`Containers`][vizro.models.Container] into the `tabs` argument of the [`Tabs`][vizro.models.Tabs]
-
+1. Insert your [`Containers`][vizro.models.Container] into the `tabs` argument of the [`Tabs`][vizro.models.Tabs]
!!! example "Tabs"
=== "app.py"
@@ -88,52 +84,53 @@ To add [`Tabs`][vizro.models.Tabs] to your page, do the following:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - tabs:
- - title: Tab I
- type: container
- components:
- - type: graph
- figure:
- _target_: bar
- data_frame: gapminder_2007
- title: Graph 1
- x: continent
- y: lifeExp
- color: continent
- - type: graph
- figure:
- _target_: box
- data_frame: gapminder_2007
- title: Graph 2
- x: continent
- y: lifeExp
- color: continent
- - title: Tab II
- type: container
- components:
- - type: graph
- figure:
- _target_: scatter
- data_frame: gapminder_2007
- title: Graph 3
- x: gdpPercap
- y: lifeExp
- size: pop
- color: continent
- type: tabs
+ components:
+ - type: tabs
+ tabs:
+ - title: Tab I
+ type: container
+ components:
+ - type: graph
+ figure:
+ _target_: bar
+ data_frame: gapminder_2007
+ title: Graph 1
+ x: continent
+ y: lifeExp
+ color: continent
+ - type: graph
+ figure:
+ _target_: box
+ data_frame: gapminder_2007
+ title: Graph 2
+ x: continent
+ y: lifeExp
+ color: continent
+ - title: Tab II
+ type: container
+ components:
+ - type: graph
+ figure:
+ _target_: scatter
+ data_frame: gapminder_2007
+ title: Graph 3
+ x: gdpPercap
+ y: lifeExp
+ size: pop
+ color: continent
controls:
- - type: filter
- column: continent
+ - type: filter
+ column: continent
title: Tabs
```
- === "Result"
- [![Tabs]][Tabs]
+ === "Result"
+ [![Tabs]][tabs]
- [Tabs]: ../../assets/user_guides/components/tabs.png
+[tabs]: ../../assets/user_guides/components/tabs.png
diff --git a/vizro-core/docs/pages/user-guides/themes.md b/vizro-core/docs/pages/user-guides/themes.md
index 6f78441d5..ac1d6fc7b 100644
--- a/vizro-core/docs/pages/user-guides/themes.md
+++ b/vizro-core/docs/pages/user-guides/themes.md
@@ -1,15 +1,13 @@
# How to use themes
-This guide shows you how to use themes. Themes are pre-designed collections of stylings that are applied to entire charts and dashboards.
-The themes provided by Vizro are infused with our design best practices that make charts and dashboards look visually consistent and professional.
+This guide shows you how to use themes. Themes are pre-designed collections of stylings that are applied to entire charts and dashboards. The themes provided by Vizro are infused with our design best practices that make charts and dashboards look visually consistent and professional.
## Themes in dashboards
-The [`Dashboard`][vizro.models.Dashboard] model accepts an optional `theme` argument, where you can choose between
-a `vizro_dark` and a `vizro_light` theme. If not specified then `theme` defaults to `vizro_dark`. The theme is applied to the entire dashboard and its charts/components when a user first loads your dashboard. Regardless of the theme applied on first load, users can always switch between light and dark themes via the toggle button in the upper-right corner of the dashboard.
+
+The [`Dashboard`][vizro.models.Dashboard] model accepts an optional `theme` argument, where you can choose between a `vizro_dark` and a `vizro_light` theme. If not specified then `theme` defaults to `vizro_dark`. The theme is applied to the entire dashboard and its charts/components when a user first loads your dashboard. Regardless of the theme applied on first load, users can always switch between light and dark themes via the toggle button in the upper-right corner of the dashboard.
!!! example "Change theme"
=== "app.py"
-
```{.python pycafe-link hl_lines="18"}
import vizro.models as vm
import vizro.plotly.express as px
@@ -32,47 +30,40 @@ a `vizro_dark` and a `vizro_light` theme. If not specified then `theme` defaults
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml hl_lines="12"
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: scatter_matrix
- color: species
- data_frame: iris
- dimensions: ["sepal_length", "sepal_width", "petal_length", "petal_width"]
- type: graph
- title: Changing themes
+ - components:
+ - figure:
+ _target_: scatter_matrix
+ color: species
+ data_frame: iris
+ dimensions: [sepal_length, sepal_width, petal_length, petal_width]
+ type: graph
+ title: Changing themes
theme: vizro_light
```
+
=== "Result - vizro_light"
- [![Light]][Light]
+ [![Light]][light]
- [Light]: ../../assets/user_guides/themes/light.png
=== "Result - vizro_dark"
- [![Dark]][Dark]
-
- [Dark]: ../../assets/user_guides/themes/dark.png
-
+ [![Dark]][dark]
## Themes in plotly charts
You can also use our templates for plotly charts outside the dashboard. This is useful in a few contexts:
-* Creation of standalone charts to be used independently of a Vizro dashboard.
-* Rapid development of charts for eventual use in a Vizro dashboard, for example in a Jupyter Notebook.
+- Creation of standalone charts to be used independently of a Vizro dashboard.
+- Rapid development of charts for eventual use in a Vizro dashboard, for example in a Jupyter Notebook.
!!! note
+ Using `import vizro.plotly.express as px` is equal to using `import plotly.express as px`, but with the added benefit of being able to integrate the resulting chart code into a Vizro dashboard. Vizro offers a minimal layer on top of Plotly's existing charting library, allowing you to seamlessly use all the existing charts and functionalities provided by plotly.express without any modifications.
- Using `import vizro.plotly.express as px` is equivalent to using `import plotly.express as px`,
- but with the added benefit of being able to integrate the resulting chart code into a Vizro dashboard.
- Vizro offers a minimal layer on top of Plotly's existing charting library, allowing you to seamlessly use all the
- existing charts and functionalities provided by plotly.express without any modifications.
-
-Our `vizro_dark` and `vizro_light` themes are automatically registered to `plotly.io.templates` when importing Vizro.
-Consult the plotly documentation for [more details on how templates work in plotly](https://plotly.com/python/templates/#theming-and-templates).
+Our `vizro_dark` and `vizro_light` themes are automatically registered to `plotly.io.templates` when importing Vizro. Consult the plotly documentation for [more details on how templates work in plotly](https://plotly.com/python/templates/#theming-and-templates).
By default, plots imported from `vizro.plotly.express` have the `vizro_dark` theme applied. This can be altered either globally or for individual plots.
@@ -87,14 +78,20 @@ pio.templates.default = "vizro_light"
```
### Set themes for selected charts
+
To change the template for a selected chart only, use the `template` parameter and run:
```python
import vizro.plotly.express as px
df = px.data.iris()
-px.scatter_matrix(df,
- dimensions=["sepal_length", "sepal_width", "petal_length", "petal_width"],
- color="species",
- template="vizro_light")
+px.scatter_matrix(
+ df,
+ dimensions=["sepal_length", "sepal_width", "petal_length", "petal_width"],
+ color="species",
+ template="vizro_light",
+)
```
+
+[dark]: ../../assets/user_guides/themes/dark.png
+[light]: ../../assets/user_guides/themes/light.png
diff --git a/vizro-core/docs/pages/user-guides/visual-formatting.md b/vizro-core/docs/pages/user-guides/visual-formatting.md
index 7b384f3e9..56d1d2d52 100644
--- a/vizro-core/docs/pages/user-guides/visual-formatting.md
+++ b/vizro-core/docs/pages/user-guides/visual-formatting.md
@@ -1,17 +1,13 @@
# How to customize the style of Vizro dashboards
-Vizro has a default styling to help users with no design experience get started.
-There are several options if you want to customize the style:
+Vizro has a default styling to help users with no design experience get started. There are several options if you want to customize the style:
-* **[Configure the `Layout`](layouts.md)**: Customize the arrangement of your components inside your Vizro dashboard.
+- **[Configure the `Layout`](layouts.md)**: Customize the arrangement of your components inside your Vizro dashboard.
-* **[Apply a theme](themes.md)**: Choose between a dark or light theme.
+- **[Apply a theme](themes.md)**: Choose between a dark or light theme.
-* **[Manage assets](assets.md)**: Enhance your dashboard by adding images, scripts, and stylesheets to your assets folder.
+- **[Manage assets](assets.md)**: Enhance your dashboard by adding images, scripts, and stylesheets to your assets folder.
-* **[Customize CSS](custom-css.md)**: Incorporate custom CSS to deviate from the default styling and create a
-unique appearance for your Vizro dashboard.
+- **[Customize CSS](custom-css.md)**: Incorporate custom CSS to deviate from the default styling and create a unique appearance for your Vizro dashboard.
-* **[Customize your `component`](components.md)**: Change the appearance of components like the [Graph](graph.md), the
-[Table](table.md) and the [AgGrid](table.md), by passing extra arguments. Refer to the relevant user guide for
-more details.
+- **[Customize your `component`](components.md)**: Change the appearance of components like the [Graph](graph.md), the [Table](table.md) and the [AgGrid](table.md), by passing extra arguments. Refer to the relevant user guide for more details.
diff --git a/vizro-core/examples/README.md b/vizro-core/examples/README.md
index 72146bfb7..53cf932b7 100644
--- a/vizro-core/examples/README.md
+++ b/vizro-core/examples/README.md
@@ -4,8 +4,7 @@ Please note that this folder contains only example dashboards that are still **i
### Vizro examples gallery
-To view a comprehensive list of available demos, please visit our [examples gallery](http://vizro.mckinsey.com/).
-There, you can explore a wide range of dashboards and applications created with Vizro.
+To view a comprehensive list of available demos, please visit our [examples gallery](http://vizro.mckinsey.com/). There, you can explore a wide range of dashboards and applications created with Vizro.
diff --git a/vizro-core/examples/visual-vocabulary/README.md b/vizro-core/examples/visual-vocabulary/README.md
index 3b298520e..e59b3103c 100644
--- a/vizro-core/examples/visual-vocabulary/README.md
+++ b/vizro-core/examples/visual-vocabulary/README.md
@@ -2,14 +2,11 @@
### Welcome to our visual vocabulary dashboard! 🎨
-This dashboard serves as a comprehensive guide for selecting and creating various types of charts. It helps you decide
-when to use each chart type, and offers sample Python code using [Plotly](https://plotly.com/python/), and
-instructions for embedding these charts into a [Vizro](https://github.com/mckinsey/vizro) dashboard.
+This dashboard serves as a comprehensive guide for selecting and creating various types of charts. It helps you decide when to use each chart type, and offers sample Python code using [Plotly](https://plotly.com/python/), and instructions for embedding these charts into a [Vizro](https://github.com/mckinsey/vizro) dashboard.
The charts in this dashboard are designed to make it easy for anyone to create beautiful and sophisticated visuals.
-Our goal is to help you understand best practices in data visualization, ensure your charts effectively communicate
-your message, and streamline the creation of high-quality, interactive visualizations.
+Our goal is to help you understand best practices in data visualization, ensure your charts effectively communicate your message, and streamline the creation of high-quality, interactive visualizations.
Created by:
@@ -19,12 +16,9 @@ Created by:
Inspired by:
-- [The FT Visual Vocabulary](https://github.com/Financial-Times/chart-doctor/blob/main/visual-vocabulary/README.md):
- [Alan Smith](https://github.com/alansmithy), [Chris Campbell](https://github.com/digitalcampbell), Ian Bott,
- Liz Faunce, Graham Parrish, Billy Ehrenberg, Paul McCallum, [Martin Stabe](https://github.com/martinstabe).
+- [The FT Visual Vocabulary](https://github.com/Financial-Times/chart-doctor/blob/main/visual-vocabulary/README.md): [Alan Smith](https://github.com/alansmithy), [Chris Campbell](https://github.com/digitalcampbell), Ian Bott, Liz Faunce, Graham Parrish, Billy Ehrenberg, Paul McCallum, [Martin Stabe](https://github.com/martinstabe).
-- [The Graphic Continuum](https://www.informationisbeautifulawards.com/showcase/611-the-graphic-continuum):
- Jon Swabish and Severino Ribecca
+- [The Graphic Continuum](https://www.informationisbeautifulawards.com/showcase/611-the-graphic-continuum): Jon Swabish and Severino Ribecca
Credits and sources:
@@ -102,13 +96,12 @@ The dashboard is still in development. Below is an overview of the chart types f
Contributions are welcome! To contribute a chart, follow the steps below:
1. Check that a `svg` file named after the chart type is contained in the [assets](https://github.com/mckinsey/vizro/tree/main/vizro-core/examples/visual-vocabulary/assets/images/charts) folder. If not, [raise an issue](https://github.com/mckinsey/vizro/issues) in the repository.
-2. Add a `.py` file containing a code example of the chart type in the `pages/examples` folder, for instance, `area.py`. Take a look at existing examples.
-3. Create a new page for the chart type and add it to the relevant category `.py` file such as `correlation.py`,
- `deviation.py`, `distribution.py`, etc. Ensure you add the page to the list of `pages` at the end of the `.py` file.
-4. Remove the `IncompletePage(..)` entry for that chart type in `chart_groups.py`.
-5. Update this `README.md` with the new chart type, its status, category, and API links.
+1. Add a `.py` file containing a code example of the chart type in the `pages/examples` folder, for instance, `area.py`. Take a look at existing examples.
+1. Create a new page for the chart type and add it to the relevant category `.py` file such as `correlation.py`, `deviation.py`, `distribution.py`, etc. Ensure you add the page to the list of `pages` at the end of the `.py` file.
+1. Remove the `IncompletePage(..)` entry for that chart type in `chart_groups.py`.
+1. Update this `README.md` with the new chart type, its status, category, and API links.
## How to run the example locally
1. Run the example with the command `hatch run example visual-vocabulary`.
-2. You should now be able to access the app locally via http://127.0.0.1:8051/.
+1. You should now be able to access the app locally via http://127.0.0.1:8051/.
Run and edit this code in PyCafe
-
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - text: |
- 
+ - components:
+ - text: |
+ 
- Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
+ Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
- Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
+ Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
- Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
- title: My card with image!
- type: card
- title: Placing Images
+ Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
+ title: My card with image!
+ type: card
+ title: Placing Images
```
- === "Result"
- [![CardImageDefault]][CardImageDefault]
- [CardImageDefault]: ../../assets/user_guides/components/card_image_default.png
+ === "Result"
+ [![CardImageDefault]][cardimagedefault]
!!! note
-
- Note that inserting images using html is by default turned off by the `dcc.Markdown` to prevent users being exposed
- to cross-site scripting attacks. If you need to turn it on, a custom component would have to be created.
+ Note that inserting images using HTML is by default turned off by the `dcc.Markdown` to prevent users being exposed to cross-site scripting attacks. If you need to turn it on, a custom component would have to be created.
You might notice that the image is quite large. You'll find out how to style images in terms of their position and size in the next section.
-
### Style a card image
To change the size or position of the image, add a URL hash to your image like this:
``
-Note the added URL hash `#my-image`. Now create a CSS file placed in your `assets` folder
-and give an attribute selector to select images with that matching URL hash.
+Note the added URL hash `#my-image`. Now create a CSS file placed in your `assets` folder and give an attribute selector to select images with that matching URL hash.
!!! example "Card with styled image"
=== "images.css"
- ```css
- img[src*="#my-image"] {
- width: 120px;
- height: 120px;
- }
- ```
+ ```css
+ img[src*="#my-image"] {
+ width: 120px;
+ height: 120px;
+ }
+ ```
+
=== "app.py"
```py
import vizro.models as vm
@@ -313,23 +303,22 @@ and give an attribute selector to select images with that matching URL hash.
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - text: |
- 
+ - components:
+ - text: |
+ 
- Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
+ Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
- Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
+ Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
- Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
- title: My card with image!
- type: card
- title: Styling Images
+ Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
+ title: My card with image!
+ type: card
+ title: Styling Images
```
- === "Result"
- [![CardImageStyled]][CardImageStyled]
- [CardImageStyled]: ../../assets/user_guides/components/card_image_styled.png
+ === "Result"
+ [![CardImageStyled]][cardimagestyled]
Use the following pre-defined URL hashes in your image path to apply Vizro's default styling.
@@ -341,12 +330,13 @@ Use the following pre-defined URL hashes in your image path to apply Vizro's def
!!! example "Card with floating image"
=== "images.css"
- ```css
- img[src*="#my-image"] {
- width: 120px;
- height: 120px;
- }
- ```
+ ```css
+ img[src*="#my-image"] {
+ width: 120px;
+ height: 120px;
+ }
+ ```
+
=== "app.py"
```py
import vizro.models as vm
@@ -389,29 +379,28 @@ Use the following pre-defined URL hashes in your image path to apply Vizro's def
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - text: |
- 
+ - components:
+ - text: |
+ 
- Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
+ Commodi repudiandae consequuntur voluptatum laborum numquam blanditiis harum quisquam eius sed odit.
- Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
+ Fugiat iusto fuga praesentium option, eaque rerum! Provident similique accusantium nemo autem.
- Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
+ Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
- Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
+ Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
- Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
+ Obcaecati tenetur iure eius earum ut molestias architecto voluptate aliquam nihil, eveniet aliquid.
- Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
- title: My card with floating image!
- type: card
- title: Floating Images
+ Culpa officia aut! Impedit sit sunt quaerat, odit, tenetur error, harum nesciunt ipsum debitis quas.
+ title: My card with floating image!
+ type: card
+ title: Floating Images
```
- === "Result"
- [![CardImageFloating]][CardImageFloating]
- [CardImageFloating]: ../../assets/user_guides/components/card_image_floating.png
+ === "Result"
+ [![CardImageFloating]][cardimagefloating]
#### Card with icon
@@ -442,38 +431,34 @@ Use the following pre-defined URL hashes in your image path to apply Vizro's def
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - text: |
- 
+ - components:
+ - text: |
+ 
- ### Card Title
+ ### Card Title
- Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut fringilla dictum lacus eget fringilla.
- Maecenas in various nibh, quis venenatis nulla. Integer et libero ultrices, scelerisque velit sed.
- type: card
- title: Card with icon
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut fringilla dictum lacus eget fringilla.
+ Maecenas in various nibh, quis venenatis nulla. Integer et libero ultrices, scelerisque velit sed.
+ type: card
+ title: Card with icon
```
- === "Result"
- [![CardIcon]][CardIcon]
-
- [CardIcon]: ../../assets/user_guides/components/card_icon.png
+ === "Result"
+ [![CardIcon]][cardicon]
### Make an icon responsive to theme switch
-To make an icon responsive to the theme switch, override the value of the [`filter` CSS property](https://developer.mozilla.org/en-US/docs/Web/CSS/filter).
-The `filter` CSS property lets you add visual effects to elements using different functions. In our example, we're using the `--inverse-color` CSS variable from the Vizro theme.
-It uses the CSS `invert()` function to flip the color of the icon when you switch themes. Note that this only works if your initial icon has a white fill color. If your icon is not white, you can change its color by adding `fill="white"` to the SVG code.
-Assign the predefined CSS variable `--inverse-color` to the `filter` property of your selected icon.
+To make an icon responsive to the theme switch, override the value of the [`filter` CSS property](https://developer.mozilla.org/en-US/docs/Web/CSS/filter). The `filter` CSS property lets you add visual effects to elements using different functions. In our example, we're using the `--inverse-color` CSS variable from the Vizro theme. It uses the CSS `invert()` function to flip the color of the icon when you switch themes. Note that this only works if your initial icon has a white fill color. If your icon is not white, you can change its color by adding `fill="white"` to the SVG code. Assign the predefined CSS variable `--inverse-color` to the `filter` property of your selected icon.
```css
img[src*="#my-image"] {
- filter: var(--inverse-color);
+ filter: var(--inverse-color);
}
```
@@ -482,18 +467,15 @@ img[src*="#my-image"] {
### Create a navigation card
-This section describes how to use the [`Card`][vizro.models.Card] component to create a navigation card,
-enabling users to navigate to another page by clicking on the card area.
+This section describes how to use the [`Card`][vizro.models.Card] component to create a navigation card, enabling users to navigate to another page by clicking on the card area.
-For a button-style link navigation component, see the [separate guide on creating a link button](#create-a-link-button).
-To configure the navigation panel on the left hand side of the screen, refer to the
-[separate guide on navigation](navigation.md).
+For a button-style link navigation component, see the [separate guide on creating a link button](#create-a-link-button). To configure the navigation panel on the left hand side of the screen, refer to the [separate guide on navigation](navigation.md).
To create a navigation card:
1. Insert the [`Card`][vizro.models.Card] into the `components` argument of the [`Page`][vizro.models.Page].
-2. Pass your markdown text to the `Card.text`.
-3. Pass a relative or absolute URL to the `Card.href`.
+1. Pass your markdown text to the `Card.text`.
+1. Pass a relative or absolute URL to the `Card.href`.
!!! example "Navigation Card"
=== "app.py"
@@ -537,72 +519,65 @@ To create a navigation card:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - text: |
- ### Filters and parameters
-
- Leads to the first page on click
- href: /filters-and-parameters
- type: card
- - text: |
- ### Google - External Link
-
- Leads to an external link on click.
- href: https://google.com
- type: card
- title: Homepage
- - components:
- - figure:
- _target_: scatter
- color: sepal_width
- data_frame: iris
- x: sepal_length
- y: petal_width
- type: graph
- title: Filters and parameters
+ - components:
+ - text: |
+ ### Filters and parameters
+
+ Leads to the first page on click
+ href: /filters-and-parameters
+ type: card
+ - text: |
+ ### Google - External Link
+
+ Leads to an external link on click.
+ href: https://google.com
+ type: card
+ title: Homepage
+ - components:
+ - figure:
+ _target_: scatter
+ color: sepal_width
+ data_frame: iris
+ x: sepal_length
+ y: petal_width
+ type: graph
+ title: Filters and parameters
```
- === "Result"
- [![NavCard]][NavCard]
- [NavCard]: ../../assets/user_guides/components/nav_card.png
+ === "Result"
+ [![NavCard]][navcard]
If you now click on the card area, you should automatically be redirected to the relevant `href`.
!!! note
-
When using the [`Card`][vizro.models.Card], keep the following in mind:
- If the href given is a relative URL, it should match the `path` of the [`Page`][vizro.models.Page] that the [`Card`][vizro.models.Card] should navigate to.
- If the href given is an absolute link, it should start with `https://` or an equivalent protocol.
-
### Create a KPI card
-To create a KPI card, you can use the existing KPI card functions from [`vizro.figures`](../API-reference/figure-callables.md).
-Unlike the static text card `vm.Card`, a KPI card must be created using a figure function,
-which enables the text content of the KPI to change based on input from controls or actions.
+
+To create a KPI card, you can use the existing KPI card functions from [`vizro.figures`](../API-reference/figure-callables.md). Unlike the static text card `vm.Card`, a KPI card must be created using a figure function, which enables the text content of the KPI to change based on input from controls or actions.
For detailed examples on how to create a KPI card, refer to the [figure user guide on KPI cards](figure.md#key-performance-indicator-kpi-cards).
## Buttons
-The Button component is commonly used for interactive dashboard interactions
-such as form submissions, navigation links, and other action triggers.
-
-To add a [`Button`][vizro.models.Button], insert it into the `components` argument of the
-[`Page`][vizro.models.Page].
+The Button component is commonly used for interactive dashboard interactions such as form submissions, navigation links, and other action triggers.
+To add a [`Button`][vizro.models.Button], insert it into the `components` argument of the [`Page`][vizro.models.Page].
### Customize button text
You can configure the `text` argument to alter the display text of the [`Button`][vizro.models.Button].
!!! example "Customize text"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -616,26 +591,24 @@ You can configure the `text` argument to alter the display text of the [`Button`
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- components:
- - type: button
- text: I'm a button!
+ - type: button
+ text: I'm a button!
title: Button with text
```
- === "Result"
- [![ButtonText]][ButtonText]
-
- [ButtonText]: ../../assets/user_guides/components/button_text.png
+ === "Result"
+ [![ButtonText]][buttontext]
### Create a link button
-To navigate to a different page using a button with an anchor tag, assign an absolute or relative URL to the
-`Button.href`.
+To navigate to a different page using a button with an anchor tag, assign an absolute or relative URL to the `Button.href`.
```python
import vizro.models as vm
@@ -645,16 +618,11 @@ vm.Button(text="Leave us a star! ⭐", href="https://github.com/mckinsey/vizro")
### Attach an action
-You can use the [`Button`][vizro.models.Button] to trigger predefined action functions, such as exporting data.
-To explore the available options for [`Actions`][vizro.models.Action], refer to our [API reference][vizro.actions].
-Use the `Button.actions` argument to specify which action function executes when the button is clicked.
-
-The example below demonstrates how to configure a button to export the filtered data of a target chart using the
-[export_data][vizro.actions.export_data] action function.
+You can use the [`Button`][vizro.models.Button] to trigger predefined action functions, such as exporting data. To explore the available options for [`Actions`][vizro.models.Action], refer to our [API reference][vizro.actions]. Use the `Button.actions` argument to specify which action function executes when the button is clicked.
+The example below demonstrates how to configure a button to export the filtered data of a target chart using the [export_data][vizro.actions.export_data] action function.
!!! example "Button with action"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -690,29 +658,30 @@ The example below demonstrates how to configure a button to export the filtered
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- components:
- - figure:
- _target_: scatter
- x: sepal_width
- y: sepal_length
- color: species
- size: petal_length
- data_frame: iris
- id: scatter_chart
- type: graph
- - type: button
- text: Export data
- id: export_data
- actions:
- - function:
- _target_: export_data
- targets:
- - scatter_chart
+ - figure:
+ _target_: scatter
+ x: sepal_width
+ y: sepal_length
+ color: species
+ size: petal_length
+ data_frame: iris
+ id: scatter_chart
+ type: graph
+ - type: button
+ text: Export data
+ id: export_data
+ actions:
+ - function:
+ _target_: export_data
+ targets:
+ - scatter_chart
controls:
- column: species
selector:
@@ -728,14 +697,13 @@ The example below demonstrates how to configure a button to export the filtered
- [1]
title: My first page
```
- === "Result"
- [![Button]][Button]
- [Button]: ../../assets/user_guides/components/button.png
+ === "Result"
+ [![Button]][button]
### Use as a control
-The [`Button`][vizro.models.Button] component is currently reserved to be used inside the main panel (right-side) of the dashboard.
-However, there might be use cases where one would like to place the `Button` inside the control panel (left-side) with the other controls.
+
+The [`Button`][vizro.models.Button] component is currently reserved to be used inside the main panel (right-side) of the dashboard. However, there might be use cases where one would like to place the `Button` inside the control panel (left-side) with the other controls.
In this case, follow the user-guide outlined for [creating custom components](custom-components.md) and manually add the `Button` as a valid type to the `controls` argument by running the following lines before your dashboard configurations:
@@ -748,3 +716,13 @@ vm.Page.add_type("controls", vm.Button)
# Add dashboard configurations below
...
```
+
+[button]: ../../assets/user_guides/components/button.png
+[buttontext]: ../../assets/user_guides/components/button_text.png
+[card]: ../../assets/user_guides/components/card.png
+[cardicon]: ../../assets/user_guides/components/card_icon.png
+[cardimagedefault]: ../../assets/user_guides/components/card_image_default.png
+[cardimagefloating]: ../../assets/user_guides/components/card_image_floating.png
+[cardimagestyled]: ../../assets/user_guides/components/card_image_styled.png
+[cardtext]: ../../assets/user_guides/components/card_text.png
+[navcard]: ../../assets/user_guides/components/nav_card.png
diff --git a/vizro-core/docs/pages/user-guides/components.md b/vizro-core/docs/pages/user-guides/components.md
index 106bf6a0b..45ea5a123 100755
--- a/vizro-core/docs/pages/user-guides/components.md
+++ b/vizro-core/docs/pages/user-guides/components.md
@@ -1,8 +1,6 @@
# Components
-The [`Page`][vizro.models.Page] model accepts the `components` argument, where you can enter any of the components
-listed below to fill your dashboard with visuals.
-
+The [`Page`][vizro.models.Page] model accepts the `components` argument, where you can enter any of the components listed below to fill your dashboard with visuals.
@@ -38,7 +36,6 @@ listed below to fill your dashboard with visuals.
[:octicons-arrow-right-24: View user guide](card-button.md)
-
- :octicons-table-16:{ .lg .middle } __Containers__
---
diff --git a/vizro-core/docs/pages/user-guides/container.md b/vizro-core/docs/pages/user-guides/container.md
index c7e327c5f..2f379709e 100755
--- a/vizro-core/docs/pages/user-guides/container.md
+++ b/vizro-core/docs/pages/user-guides/container.md
@@ -2,30 +2,22 @@
This guide shows you how to use containers to group your components into sections and subsections within the page.
-A [`Container`][vizro.models.Container] complements the idea of a [`Page`][vizro.models.Page], and the two models have almost identical arguments.
- [`Page.layout`](layouts.md) offers a way to structure the overall layout of the page, and a `Container` enables more granular control within a specific section of that page.
+A [`Container`][vizro.models.Container] complements the idea of a [`Page`][vizro.models.Page], and the two models have almost identical arguments. [`Page.layout`](layouts.md) offers a way to structure the overall layout of the page, and a `Container` enables more granular control within a specific section of that page.
-While there is currently no clear difference in rendering, extra functionality will be added to the `Container` soon (including controls specific to that container),
-enhancing the ability to manage related components.
+While there is currently no clear difference in rendering, extra functionality will be added to the `Container` soon (including controls specific to that container), enhancing the ability to manage related components.
!!! note "Displaying multiple containers inside Tabs"
-
An alternative way to display multiple containers on one page is to place them inside [Tabs](tabs.md).
- [`Tabs`][vizro.models.Tabs] organize and separate groups of related content in a dashboard, letting users switch between different sections or views.
- They are a way of putting multiple containers into the same screen space, and letting the user switch between them.
+ [`Tabs`][vizro.models.Tabs] organize and separate groups of related content in a dashboard, letting users switch between different sections or views. They are a way of putting multiple containers into the same screen space, and letting the user switch between them.
{ width="500" }
-
-
## When to use containers
-In general, any arbitrarily granular layout can already be achieved by [using `Page.layout`](layouts.md) alone and is our
-recommended approach if you want to arrange components on a page with consistent row and/or column spacing.
-`Page.layout` has a `grid` argument that sets the overall layout of the page.
-`Container.layout` also has a `grid` argument. This enables you to insert a further `grid` into a component's space on the page,
-enabling more granular control by breaking the overall page grid into subgrids.
+In general, any arbitrarily granular layout can already be achieved by [using `Page.layout`](layouts.md) alone and is our recommended approach if you want to arrange components on a page with consistent row and/or column spacing.
+
+`Page.layout` has a `grid` argument that sets the overall layout of the page. `Container.layout` also has a `grid` argument. This enables you to insert a further `grid` into a component's space on the page, enabling more granular control by breaking the overall page grid into subgrids.
Here are a few cases where you might want to use a `Container` instead of `Page.layout`:
@@ -34,14 +26,14 @@ Here are a few cases where you might want to use a `Container` instead of `Page.
- If you want different row and column spacing between subgrids
- If you want to apply controls to selected subgrids (will be supported soon)
-
## Basic containers
+
To add a [`Container`][vizro.models.Container] to your page, do the following:
1. Insert the `Container` into the `components` argument of the [`Page`][vizro.models.Page]
-2. Set a `title` for your `Container`
-3. Configure your `components`, [read the overview page for various options](components.md)
-4. (optional) Configure your `layout`, see [the guide on `Layout`](layouts.md)
+1. Set a `title` for your `Container`
+1. Configure your `components`, [read the overview page for various options](components.md)
+1. (optional) Configure your `layout`, see [the guide on `Layout`](layouts.md)
!!! example "Container"
=== "app.py"
@@ -105,7 +97,7 @@ To add a [`Container`][vizro.models.Container] to your page, do the following:
```
1. Note that the `Page.layout` argument is not specified here and will therefore defaults to `[[0], [1]]`, meaning the containers will be **vertically stacked** down the page in one column.
- 2. **Horizontally stack** the components side-by-side inside this `Container` in one row.
+ 1. **Horizontally stack** the components side-by-side inside this `Container` in one row.
=== "app.yaml"
```yaml
@@ -149,27 +141,20 @@ To add a [`Container`][vizro.models.Container] to your page, do the following:
title: Container II
title: Containers
```
- === "Result"
- [![Container]][Container]
- [Container]: ../../assets/user_guides/components/containers.png
+ === "Result"
+ [![Container]][container]
Note that an almost identical layout can also be achieved using solely the [`Page.layout`](layouts.md) by configuring the `Page.layout` as `vm.Layout(grid = [[0, 1], [2, 2]])`.
## Nested containers
-Containers can be nested, providing a hierarchical structure for organizing components.
-This nesting capability enables users to create more complex layouts and manage related components at any level of granularity.
+
+Containers can be nested, providing a hierarchical structure for organizing components. This nesting capability enables users to create more complex layouts and manage related components at any level of granularity.
To create nested containers, add a `Container` to the `components` argument of another `Container`.
```python title="Example"
-vm.Container(
- title="Parent Container",
- components=[
- vm.Container(
- title="Child Container",
- components=[vm.Button()]
- )
- ]
-)
+vm.Container(title="Parent Container", components=[vm.Container(title="Child Container", components=[vm.Button()])])
```
+
+[container]: ../../assets/user_guides/components/containers.png
diff --git a/vizro-core/docs/pages/user-guides/custom-actions.md b/vizro-core/docs/pages/user-guides/custom-actions.md
index e5fa3afd8..2fb66cd2c 100644
--- a/vizro-core/docs/pages/user-guides/custom-actions.md
+++ b/vizro-core/docs/pages/user-guides/custom-actions.md
@@ -1,17 +1,16 @@
# How to create custom actions
-This guide demonstrates the usage of custom actions, an idea that shares similarities with, but is not identical to [callbacks](https://dash.plotly.com/basic-callbacks) in `Dash`.
-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.
+This guide demonstrates the usage of custom actions, an idea that shares similarities with, but is not identical to [callbacks](https://dash.plotly.com/basic-callbacks) in `Dash`. 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.
+
## Simple custom action
Custom actions enable you to implement your own action function. Simply do the following:
1. define a function
-2. decorate it with the `@capture("action")` decorator
-3. add it as a `function` argument inside the [`Action`][vizro.models.Action] model
+1. decorate it with the `@capture("action")` decorator
+1. add it as a `function` argument inside the [`Action`][vizro.models.Action] model
The following example shows how to create a custom action that postpones execution of the next action in the chain for `t` seconds.
@@ -58,27 +57,24 @@ The following example shows how to create a custom action that postpones executi
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
- ```yaml
- # Custom actions are currently only possible via Python configuration
- ```
-
+ Custom actions are currently only possible via Python configuration.
+
## Interact with inputs and outputs
+
When a custom action needs to interact with the dashboard, it is possible to define `inputs` and `outputs` for the custom action.
-- `inputs` represents dashboard component properties whose values are passed to the custom action function as arguments.
-It is a list of strings in the format `"."` (for example, `"my_selector.value`").
-- `outputs` represents dashboard component properties corresponding to the custom action function return value(s).
-Similar to `inputs`, it is a list of strings in the format `"."` (for example, `"my_card.children"`).
+- `inputs` represents dashboard component properties whose values are passed to the custom action function as arguments. It is a list of strings in the format `"."` (for example, `"my_selector.value`").
+- `outputs` represents dashboard component properties corresponding to the custom action function return value(s). Similar to `inputs`, it is a list of strings in the format `"."` (for example, `"my_card.children"`).
### Example of `value` as input
-The following example shows a custom action that takes the `value` of the `vm.RadioItem` and returns it inside a
-[`Card`][vizro.models.Card] component.
-!!! example "Display `value` in Card"
+The following example shows a custom action that takes the `value` of the `vm.RadioItem` and returns it inside a [`Card`][vizro.models.Card] component.
+!!! example "Display `value` in Card"
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -113,23 +109,18 @@ The following example shows a custom action that takes the `value` of the `vm.Ra
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
- === "app.yaml"
- ```yaml
- # Custom actions are currently only possible via Python configuration
- ```
- === "Result"
- [![ValueAction]][ValueAction]
- [ValueAction]: ../../assets/user_guides/custom_actions/value_as_input.png
+ === "app.yaml"
+ Custom actions are currently only possible via Python configuration.
+ === "Result"
+ [![ValueAction]][valueaction]
### Example of `clickData` as input
-The following example shows how to create a custom action that shows the `clickData` of a chart in a
-[`Card`][vizro.models.Card] component. For further information on the structure and content of the `clickData`
-property, refer to the Dash documentation on [interactive visualizations](https://dash.plotly.com/interactive-graphing).
-!!! example "Display `clickData` in Card"
+The following example shows how to create a custom action that shows the `clickData` of a chart in a [`Card`][vizro.models.Card] component. For further information on the structure and content of the `clickData` property, refer to the Dash documentation on [interactive visualizations](https://dash.plotly.com/interactive-graphing).
+!!! example "Display `clickData` in Card"
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -173,21 +164,18 @@ property, refer to the Dash documentation on [interactive visualizations](https:
```
1. Just as for any Python function, the names of the arguments `show_species` and `points_data` are arbitrary and do not need to match on to the names of `inputs` in any particular way.
- 2. We _bind_ (set) the argument `show_species` to the value `True` in the initial specification of the `function` field. These are static values that are fixed when the dashboard is _built_.
- 3. The content of `inputs` will "fill in the gaps" by setting values for the remaining unbound arguments in `my_custom_action`. Here there is one such argument, named `points_data`. Values for these are bound _dynamically at runtime_ to reflect the live state of your dashboard.
+ 1. We _bind_ (set) the argument `show_species` to the value `True` in the initial specification of the `function` field. These are static values that are fixed when the dashboard is _built_.
+ 1. The content of `inputs` will "fill in the gaps" by setting values for the remaining unbound arguments in `my_custom_action`. Here there is one such argument, named `points_data`. Values for these are bound _dynamically at runtime_ to reflect the live state of your dashboard.
+
=== "app.yaml"
- ```yaml
- # Custom actions are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomAction]][CustomAction]
+ Custom actions are currently only possible via Python configuration.
- [CustomAction]: ../../assets/user_guides/custom_actions/clickdata_as_input.png
+ === "Result"
+ [![CustomAction]][customaction]
## Multiple return values
-The return value of the custom action function is propagated to the dashboard components that are defined in the `outputs` argument of the [`Action`][vizro.models.Action] model.
-If there is a single `output` defined then the function return value is directly assigned to the component property.
-If there are multiple `outputs` defined then the return value is iterated through and each part is assigned to each component property given in `outputs` in turn. This behavior is identical to Python's flexibility in managing multiple return values.
+
+The return value of the custom action function is propagated to the dashboard components that are defined in the `outputs` argument of the [`Action`][vizro.models.Action] model. If there is a single `output` defined then the function return value is directly assigned to the component property. If there are multiple `outputs` defined then the return value is iterated through and each part is assigned to each component property given in `outputs` in turn. This behavior is identical to Python's flexibility in managing multiple return values.
!!! example "Multiple return values"
=== "app.py"
@@ -246,17 +234,17 @@ If there are multiple `outputs` defined then the return value is iterated throug
```
1. `my_custom_action` returns two values (which will be in Python tuple).
- 2. These values are assigned to the `outputs` in the same order.
- === "app.yaml"
- ```yaml
- # Custom actions are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomAction2]][CustomAction2]
+ 1. These values are assigned to the `outputs` in the same order.
- [CustomAction2]: ../../assets/user_guides/custom_actions/custom_action_multiple_return_values.png
+ === "app.yaml"
+ Custom actions are currently only possible via Python configuration.
+ === "Result"
+ [![CustomAction2]][customaction2]
!!! warning
+ Note that users of this package are responsible for the content of any custom action function that they write. Take care to avoid leaking any sensitive information or exposing to any security threat during implementation. You should always [treat the content of user input as untrusted](https://community.plotly.com/t/writing-secure-dash-apps-community-thread/54619).
- Note that users of this package are responsible for the content of any custom action function that they write - especially with regard to leaking any sensitive information or exposing to any security threat during implementation. You should always [treat the content of user input as untrusted](https://community.plotly.com/t/writing-secure-dash-apps-community-thread/54619).
+[customaction]: ../../assets/user_guides/custom_actions/clickdata_as_input.png
+[customaction2]: ../../assets/user_guides/custom_actions/custom_action_multiple_return_values.png
+[valueaction]: ../../assets/user_guides/custom_actions/value_as_input.png
diff --git a/vizro-core/docs/pages/user-guides/custom-charts.md b/vizro-core/docs/pages/user-guides/custom-charts.md
index cb26614c8..1b77d0869 100644
--- a/vizro-core/docs/pages/user-guides/custom-charts.md
+++ b/vizro-core/docs/pages/user-guides/custom-charts.md
@@ -1,9 +1,9 @@
# 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 graphs](graph.md).
+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 graphs](graph.md).
## When to use a custom chart
+
In general, you should use the custom chart decorator `@capture("graph")` if your plotly chart needs any post-update calls or customization. For example:
- You want to use any of the post figure update calls by `plotly` such as `update_layout`, `update_xaxes`, `update_traces` (for more details, see the docs on [plotly's update calls](https://plotly.com/python/creating-and-updating-figures/#other-update-methods))
@@ -12,11 +12,10 @@ In general, you should use the custom chart decorator `@capture("graph")` if you
## Steps to create a custom chart
1. Define a function that returns a `go.Figure()`.
-2. Decorate it with `@capture("graph")`.
-3. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
-4. The visualization should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments
-will not react to dashboard controls such as [`Filter`](filters.md).
-5. Pass your function to the `figure` argument of the [`Graph`][vizro.models.Graph] model.
+1. Decorate it with `@capture("graph")`.
+1. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
+1. The visualization should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments will not react to dashboard controls such as [`Filter`](filters.md).
+1. Pass your function to the `figure` argument of the [`Graph`][vizro.models.Graph] model.
The minimal example below can be used as a base to build more sophisticated charts.
@@ -39,12 +38,10 @@ To alter the data in the `data_frame` argument, consider using a [Filter](filter
## Enhanced `plotly.express` chart with reference line
-The below examples shows a case where we enhance an existing `plotly.express` chart. We add a new argument (`hline`), that is used to draw a grey reference line at the height determined by the value of `hline`. The important thing to note is that we then
-add a `Parameter` that enables the dashboard user to interact with the argument, and hence move the line in this case. See the `Result` tab for an animation.
+The below examples shows a case where we enhance an existing `plotly.express` chart. We add a new argument (`hline`), that is used to draw a grey reference line at the height determined by the value of `hline`. The important thing to note is that we then add a `Parameter` that enables the dashboard user to interact with the argument, and hence move the line in this case. See the `Result` tab for an animation.
!!! example "Custom `plotly.express` scatter chart with a `Parameter`"
=== "app.py"
-
```{.python pycafe-link}
import vizro.models as vm
import vizro.plotly.express as px
@@ -86,17 +83,14 @@ add a `Parameter` that enables the dashboard user to interact with the argument,
Vizro().build(dashboard).run()
```
- 1. Note that arguments of the custom chart can be parametrized. Here we choose to parametrize the `hline` argument (see below).
- 2. Here we parametrize the `hline` argument, but any other argument can be parametrized as well. Since there is complete flexibility regarding what can be derived from such arguments, the dashboard user has a wide range of customization options.
- === "app.yaml"
- ```yaml
- # Custom charts are currently only possible via Python configuration
- ```
- === "Result"
- [![Graph2]][Graph2]
+ 1. Note that arguments of the custom chart can be parametrized. Here we choose to parametrize the `hline` argument (see below).
+ 1. Here we parametrize the `hline` argument, but any other argument can be parametrized as well. Since there is complete flexibility regarding what can be derived from such arguments, the dashboard user has a wide range of customization options.
- [Graph2]: ../../assets/user_guides/custom_charts/custom_chart_showcase_parameter.gif
+ === "app.yaml"
+ Custom charts are currently only possible via Python configuration.
+ === "Result"
+ [![Graph2]][graph2]
## New Waterfall chart based on `go.Figure()`
@@ -104,7 +98,6 @@ The below examples shows a more involved use-case. We create and style a waterfa
!!! example "Custom `go.Figure()` waterfall chart with a `Parameter`"
=== "app.py"
-
```{.python pycafe-link}
import pandas as pd
import plotly.graph_objects as go
@@ -162,10 +155,10 @@ The below examples shows a more involved use-case. We create and style a waterfa
```
=== "app.yaml"
- ```yaml
- # Custom charts are currently only possible via Python configuration
- ```
+ Custom charts are currently only possible via Python configuration.
+
=== "Result"
- [![Graph3]][Graph3]
+ [![Graph3]][graph3]
- [Graph3]: ../../assets/user_guides/custom_charts/custom_chart_waterfall.png
+[graph2]: ../../assets/user_guides/custom_charts/custom_chart_showcase_parameter.gif
+[graph3]: ../../assets/user_guides/custom_charts/custom_chart_waterfall.png
diff --git a/vizro-core/docs/pages/user-guides/custom-css.md b/vizro-core/docs/pages/user-guides/custom-css.md
index dd2d22275..d5bc5f7dc 100755
--- a/vizro-core/docs/pages/user-guides/custom-css.md
+++ b/vizro-core/docs/pages/user-guides/custom-css.md
@@ -1,25 +1,20 @@
# Customizing Vizro dashboard CSS
-Vizro is opinionated about visual formatting, and some elements, such as the layout of the navigation and controls,
-are fixed. You can customize some settings such as background colors, fonts, and other styles via CSS overrides.
+Vizro is opinionated about visual formatting, and some elements, such as the layout of the navigation and controls, are fixed. You can customize some settings such as background colors, fonts, and other styles via CSS overrides.
To make customizations, you need to:
1. **Add a CSS file to your `assets` folder**. Refer to our user guide on [adding static assets](assets.md#how-to-add-static-assets).
-2. **Identify the correct CSS selector** for the component you want to style.
-3. **Change the relevant CSS properties** in your CSS file.
-
-
+1. **Identify the correct CSS selector** for the component you want to style.
+1. **Change the relevant CSS properties** in your CSS file.
## Introduction to Vizro CSS
+
For a short introduction to CSS, we recommend reading this article: [Get Started with CSS in 5 Minutes](https://www.freecodecamp.org/news/get-started-with-css-in-5-minutes-e0804813fc3e/).
-For a more comprehensive tutorial, refer to the [W3Schools CSS tutorial](https://www.w3schools.com/css/default.asp).
-The entire tutorial is beneficial, but the section on [CSS selectors](https://www.w3schools.com/css/css_selectors.asp)
-will be particularly useful.
+For a more comprehensive tutorial, refer to the [W3Schools CSS tutorial](https://www.w3schools.com/css/default.asp). The entire tutorial is beneficial, but the section on [CSS selectors](https://www.w3schools.com/css/css_selectors.asp) will be particularly useful.
-In Vizro, the CSS file is read in as an external stylesheet. The most common way of applying any styling to
-Vizro is therefore through the use of CSS selectors:
+In Vizro, the CSS file is read in as an external stylesheet. The most common way of applying any styling to Vizro is therefore through the use of CSS selectors:
- **Element Selector**: Applies the style to all elements inside the Vizro app.
@@ -33,8 +28,7 @@ Vizro is therefore through the use of CSS selectors:
}
```
-- **Class selector:** Targets all elements with the given class for styling. All CSS classes must be preceded with a
-`.` symbol.
+- **Class selector:** Targets all elements with the given class for styling. All CSS classes must be preceded with a `.` symbol.
```
.card {
@@ -50,30 +44,25 @@ Vizro is therefore through the use of CSS selectors:
}
```
-
## Identify the correct CSS selector
Use Chrome DevTools or a similar tool (Web Inspector, Web Developer Tools, etc.) to inspect the HTML document in your browser.
-1. **Open DevTools:** In Google Chrome, right-click on the app and select "Inspect" from the context menu. This opens the
-HTML document of your Vizro app.
+1. **Open DevTools:** In Google Chrome, right-click on the app and select "Inspect" from the context menu. This opens the HTML document of your Vizro app.
-
-2. **Select an element:** Suppose you want to change the background color of your cards. Click the
-"Select an element in the page to inspect it" icon in the top left corner of the inspect panel.
+1. **Select an element:** Suppose you want to change the background color of your cards. Click the "Select an element in the page to inspect it" icon in the top left corner of the inspect panel.
-3. **Find the HTML Block:** Hover over the component you want to style. The corresponding HTML block will be
-highlighted in the HTML document.
+1. **Find the HTML Block:** Hover over the component you want to style. The corresponding HTML block will be highlighted in the HTML document.
Notice that the selected HTML block corresponds to the container of the card and has a CSS class, here it is `card`.
-4. **Apply CSS:** Use this CSS class to style the card component. In your CSS file, you can write:
+1. **Apply CSS:** Use this CSS class to style the card component. In your CSS file, you can write:
```
.card {
@@ -83,25 +72,25 @@ highlighted in the HTML document.
This changes the background color for any HTML element with the `card` class.
-**Tip:** You can also test your CSS live by editing the CSS attributes in the "Elements" panel.
-For example, temporarily add `background: blue;`. Note that this change will be lost upon reloading the page.
+**Tip:** You can also test your CSS live by editing the CSS attributes in the "Elements" panel. For example, temporarily add `background: blue;`. Note that this change will be lost upon reloading the page.
-
## CSS overwrites
### Overwrite CSS globally
-To overwrite any global CSS property, you need to target the element selector and place your CSS file with the
-overwrites in the `assets` folder.
+
+To overwrite any global CSS property, you need to target the element selector and place your CSS file with the overwrites in the `assets` folder.
!!! example "Overwrite CSS globally"
=== "my_css_file.css"
- ```css
- h1, h2 {
- color: hotpink;
- }
- ```
+ ```css
+ h1,
+ h2 {
+ color: hotpink;
+ }
+ ```
+
=== "app.py"
```py
import os
@@ -134,44 +123,41 @@ overwrites in the `assets` folder.
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # This is an tag
+ - components:
+ - text: |
+ # This is an
tag
+ - components:
+ - text: |
+ # This is an tag
- ## This is an tag
+ ## This is an tag
- ###### This is an tag
- type: card
- title: Changing the header color
+ ###### This is an tag
+ type: card
+ title: Changing the header color
```
- === "Result"
- [![AssetsCSS]][AssetsCSS]
-
- [AssetsCSS]: ../../assets/user_guides/assets/css_change.png
+ === "Result"
+ [![AssetsCSS]][assetscss]
### Overwrite CSS for selected pages
-To style components for a specific page, use the page's `id` in the CSS selectors. By default, this is the
-[same as the page `title`](pages.md), but such a value might not be a valid CSS identifier.
-A suitable `id` must be unique across all models in the dashboard and should contain only alphanumeric
-characters, hyphens (`-`) and underscores (`_`). In particular, note that spaces are _not_ allowed.
+To style components for a specific page, use the page's `id` in the CSS selectors. By default, this is the [same as the page `title`](pages.md), but such a value might not be a valid CSS identifier.
+
+A suitable `id` must be unique across all models in the dashboard and should contain only alphanumeric characters, hyphens (`-`) and underscores (`_`). In particular, note that spaces are _not_ allowed.
Suppose you want to hide the page title on one page only. Here's how you can achieve this:
1. Give a valid `id` to the `Page`, for example `Page(id="page-with-hidden-title", title="Page with hidden title", ...)`.
-2. Identify the CSS class or CSS `id` you need to target. To hide the page title, you need to hide the parent container with the id `right-header`.
-3. Use the `id` to hide the content.
-4. Add your custom css file to the `assets` folder.
-
+1. Identify the CSS class or CSS `id` you need to target. To hide the page title, you need to hide the parent container with the id `right-header`.
+1. Use the `id` to hide the content.
+1. Add your custom css file to the `assets` folder.
!!! example "Hide page title on selected pages"
=== "my_css_file.css"
- ```css
- #page-with-hidden-title #right-header {
- display: none;
- }
- ```
+ ```css
+ #page-with-hidden-title #right-header {
+ display: none;
+ }
+ ```
+
=== "app.py"
```py
import vizro.models as vm
@@ -199,25 +185,24 @@ Suppose you want to hide the page title on one page only. Here's how you can ach
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Placeholder
- type: card
- title: Page with hidden title
- id: page-with-hidden-title
- - components:
- - text: |
- # Placeholder
- type: card
- title: Page with shown title
+ - components:
+ - text: |
+ # Placeholder
+ type: card
+ title: Page with hidden title
+ id: page-with-hidden-title
+ - components:
+ - text: |
+ # Placeholder
+ type: card
+ title: Page with shown title
```
- === "Result"
- [![PageTitle]][PageTitle]
-
- [PageTitle]: ../../assets/user_guides/assets/css_page_title.png
+ === "Result"
+ [![PageTitle]][pagetitle]
### Overwrite CSS for selected components
+
To adjust CSS properties for specific components, such as altering the appearance of a selected [`Card`][vizro.models.Card] rather than all Cards, you need to supply an `id` to the component you want to style.
Let's say we want to change the `background-color` and `color` of a specific `Card`.
@@ -225,41 +210,43 @@ Let's say we want to change the `background-color` and `color` of a specific `Ca
Here's how you can do it:
1. Assign a unique `id` to the relevant `Card`, for example: `Card(id="custom-card", ...)`
-2. Run your dashboard and open it in your browser
-3. View the HTML document to find the appropriate CSS class or element you need to target, as explained in the section
-on [identifying the correct CSS selector](#identify-the-correct-css-selector).
+1. Run your dashboard and open it in your browser
+1. View the HTML document to find the appropriate CSS class or element you need to target, as explained in the section on [identifying the correct CSS selector](#identify-the-correct-css-selector).
-It's essential to understand the relationship between the targeted CSS class or element and the component assigned
-`id`, for example:
+It's essential to understand the relationship between the targeted CSS class or element and the component assigned `id`, for example:
-```html title="HTML structure of a `Card`"
+
+```html title="HTML structure of a card"
-
- Lorem ipsum dolor sit amet consectetur adipisicing elit.
-
+
+
+ Lorem ipsum dolor sit amet consectetur adipisicing elit.
+
+
```
-
-* **Main element with `id`:** There is a `` with our `id="custom-card"`.
-* **Parent element:** That `` is wrapped inside a parent `` with the class name `"card"`. This is the element we need to target to change the background color.
-* **Child element:** The card text is wrapped inside a `` that is a child of the `
` with our `id`. This is the element we need to target to change the font color.
+
+- **Main element with `id`:** There is a `` with our `id="custom-card"`.
+- **Parent element:** That `` is wrapped inside a parent `` with the class name `"card"`. This is the element we need to target to change the background color.
+- **Child element:** The card text is wrapped inside a `` that is a child of the `
` with our `id`. This is the element we need to target to change the font color.
!!! example "Customizing CSS properties in selective components"
=== "my_css_file.css"
- ```css
- /* Apply styling to parent */
- .card:has(#custom-card) {
- background-color: white;
- }
+ ```css
+ /* Apply styling to parent */
+ .card:has(#custom-card) {
+ background-color: white;
+ }
+
+ /* Apply styling to child */
+ #custom-card p {
+ color: black;
+ }
+ ```
- /* Apply styling to child */
- #custom-card p {
- color: black;
- }
- ```
=== "app.py"
```py
import vizro.models as vm
@@ -285,77 +272,65 @@ It's essential to understand the relationship between the targeted CSS class or
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- Lorem ipsum dolor sit amet consectetur adipisicing elit.
- type: card
- id: custom-card
- - text: |
- Lorem ipsum dolor sit amet consectetur adipisicing elit.
- type: card
- title: Changing the card color
+ - components:
+ - text: |
+ Lorem ipsum dolor sit amet consectetur adipisicing elit.
+ type: card
+ id: custom-card
+ - text: |
+ Lorem ipsum dolor sit amet consectetur adipisicing elit.
+ type: card
+ title: Changing the card color
```
- === "Result"
- [![CardCSS]][CardCSS]
-
- [CardCSS]: ../../assets/user_guides/assets/css_change_card.png
+ === "Result"
+ [![CardCSS]][cardcss]
!!! note "Relationship between model ID and CSS ID"
+ Some Vizro components produce a single HTML element with an ID that matches the model ID, allowing you to target it directly using the CSS #id selector. Other components generate multiple HTML elements. Within these, the "core" element will have an ID matching the model ID, while non-core elements may have IDs that are variations of it, such as `{model-id}-title`.
- Some Vizro components produce a single HTML element with an ID that matches the model ID, allowing you to target it
- directly using the CSS #id selector. Other components generate multiple HTML elements. Within these, the "core"
- element will have an ID matching the model ID, while non-core elements may have IDs that are variations of it,
- such as `{model-id}-title`.
-
- In all instances, you can determine the correct selector by using Chrome DevTools or a similar tool after setting the
- appropriate model ID.
-
+ In all instances, you can determine the correct selector by using Chrome DevTools or a similar tool after setting the appropriate model ID.
## Common examples
### Make your CSS responsive to theme switches with variables
-To ensure your CSS adapts to theme changes, we recommend using CSS variables (`var`) whenever possible. For a
-comprehensive list of available variable names, refer to the
-[Bootstrap documentation](https://getbootstrap.com/docs/5.3/customize/css-variables/). Note that our
-Bootstrap stylesheet is still under development, so not all Bootstrap variables are currently available.
-Additionally, you can define your own CSS variables, as demonstrated in the example on
-[changing the container background color](#change-the-styling-of-a-container).
+
+To ensure your CSS adapts to theme changes, we recommend using CSS variables (`var`) whenever possible. For a comprehensive list of available variable names, refer to the [Bootstrap documentation](https://getbootstrap.com/docs/5.3/customize/css-variables/). Note that our Bootstrap stylesheet is still under development, so not all Bootstrap variables are currently available. Additionally, you can define your own CSS variables, as demonstrated in the example on [changing the container background color](#change-the-styling-of-a-container).
### Turn off page title
+
See the example above on [hiding the page title on selected pages](#overwrite-css-for-selected-pages).
### Change the background color of a card
+
See the example above on [customizing CSS properties in selective components](#overwrite-css-for-selected-components).
### Change the global font
+
The default fonts for a Vizro app are `Inter, sans-serif, Arial, serif`.
If you need to change the global font, perhaps to adhere to branding guidelines, follow these steps:
1. Download the desired font from a font provider such as [Google Fonts](https://fonts.google.com/).
-2. Place the font file (`.ttf`, `woff2`, etc.) into your `assets` folder. Here’s an example of what the assets folder might look like:
- 
+1. Place the font file (`.ttf`, `woff2`, etc.) into your `assets` folder. Here’s an example of what the assets folder might look like:
-3. Add the font to your CSS file using the `@font-face` rule and apply the font globally to your Vizro app, making sure
-to specify fallback fonts. Add the following to your `custom.css` file:
+ 
+1. Add the font to your CSS file using the `@font-face` rule and apply the font globally to your Vizro app, making sure to specify fallback fonts. Add the following to your `custom.css` file:
```css
@font-face {
- font-family: PlayfairDisplay;
- src: url("PlayfairDisplay-VariableFont_wght.ttf") format("truetype");
+ font-family: PlayfairDisplay;
+ src: url("PlayfairDisplay-VariableFont_wght.ttf") format("truetype");
}
* {
- font-family: PlayfairDisplay, Inter, sans-serif, Arial, serif;
+ font-family: PlayfairDisplay, Inter, sans-serif, Arial, serif;
}
```
-
-4. Note that the modification above applies solely to the dashboard font. To also change the font within the
-Plotly charts, you must specify this at the beginning of your `app.py` file:
+1. Note that the modification above applies solely to the dashboard font. To also change the font within the Plotly charts, you must specify this at the beginning of your `app.py` file:
```python
import plotly.io as pio
@@ -365,44 +340,42 @@ Plotly charts, you must specify this at the beginning of your `app.py` file:
```
### Reposition the logo
-By default, the logo appears in the top left corner of the dashboard. You can move it further to the left or right by
-adjusting the `padding` of the `#page-header` element. Here is an example of how to achieve this:
+
+By default, the logo appears in the top left corner of the dashboard. You can move it further to the left or right by adjusting the `padding` of the `#page-header` element. Here is an example of how to achieve this:
```css
#page-header {
- padding-left: 8px;
+ padding-left: 8px;
}
```
-
### Change the styling of a container
-If you want to make the subsections of your dashboard stand out more, you can do this by placing your components
-inside a [Container](container.md) and changing the container's styling, for example, background color, borders, padding, etc.
-To do this, you need to change the container's CSS class. Using the DevTool, as explained in the section on
-[identifying the correct CSS selector](#identify-the-correct-css-selector), you'll find that the CSS class for the
-`Container` is `page-component-container`. You can then use this class to set a new `background-color` and `padding`.
+If you want to make the subsections of your dashboard stand out more, you can do this by placing your components inside a [Container](container.md) and changing the container's styling, for example, background color, borders, padding, etc.
+
+To do this, you need to change the container's CSS class. Using the DevTool, as explained in the section on [identifying the correct CSS selector](#identify-the-correct-css-selector), you'll find that the CSS class for the `Container` is `page-component-container`. You can then use this class to set a new `background-color` and `padding`.
!!! example "Style a container"
=== "custom.css"
- ```css
- /* Assign a variable to the dark and light theme */
- [data-bs-theme="dark"] {
- --container-bg-color: #232632;
- }
-
- [data-bs-theme="light"] {
- --container-bg-color: #F5F6F6;
- }
+ ```css
+ /* Assign a variable to the dark and light theme */
+ [data-bs-theme="dark"] {
+ --container-bg-color: #232632;
+ }
+
+ [data-bs-theme="light"] {
+ --container-bg-color: #F5F6F6;
+ }
+
+ /* Use the custom variable var(--container-bg-color) */
+ .page-component-container {
+ background: var(--container-bg-color);
+ padding: 12px;
+ }
+ ```
- /* Use the custom variable var(--container-bg-color) */
- .page-component-container {
- background: var(--container-bg-color);
- padding: 12px;
- }
- ```
=== "app.py"
```py
import vizro.models as vm
@@ -437,12 +410,12 @@ To do this, you need to change the container's CSS class. Using the DevTool, as
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - title: "Page with subsections"
+ - title: Page with subsections
layout:
grid: [[0, 1]]
components:
- type: container
- title: "Container I"
+ title: Container I
components:
- type: graph
figure:
@@ -452,7 +425,7 @@ To do this, you need to change the container's CSS class. Using the DevTool, as
y: sepal_length
color: species
- type: container
- title: "Container II"
+ title: Container II
components:
- type: graph
figure:
@@ -462,13 +435,11 @@ To do this, you need to change the container's CSS class. Using the DevTool, as
y: sepal_length
color: species
```
- === "Result"
- [![StyleContainer]][StyleContainer]
- [StyleContainer]: ../../assets/user_guides/custom_css/style-container.png
+ === "Result"
+ [![StyleContainer]][stylecontainer]
-You will notice that the background colors of the charts are different. To align it with the colors of the container,
-you can make the charts' background transparent.
+You will notice that the background colors of the charts are different. To align it with the colors of the container, you can make the charts' background transparent.
To make the background of all charts transparent:
@@ -492,3 +463,8 @@ def custom_chart(data_frame):
```
+
+[assetscss]: ../../assets/user_guides/assets/css_change.png
+[cardcss]: ../../assets/user_guides/assets/css_change_card.png
+[pagetitle]: ../../assets/user_guides/assets/css_page_title.png
+[stylecontainer]: ../../assets/user_guides/custom_css/style-container.png
diff --git a/vizro-core/docs/pages/user-guides/custom-figures.md b/vizro-core/docs/pages/user-guides/custom-figures.md
index f135127be..3a178932f 100644
--- a/vizro-core/docs/pages/user-guides/custom-figures.md
+++ b/vizro-core/docs/pages/user-guides/custom-figures.md
@@ -1,41 +1,36 @@
# How to create custom figures
-This guide explains how to create custom figures, which is useful when you need a component that reacts to
-[filter](filters.md) and [parameter](parameters.md) controls.
+This guide explains how to create custom figures, which is 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).
## When to use a custom figure
-As described in the flowchart detailing [when to use `Figure`](figure.md), custom figures should be used if
-**both** of the following conditions are met:
+
+As described in the flowchart detailing [when to use `Figure`](figure.md), custom figures should be used if **both** of the following conditions are met:
- You need a figure that doesn't fit into the existing pre-defined components ([`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid]).
- You need a figure that isn't available in our pre-defined figure functions [`vizro.figures`](../API-reference/figure-callables.md).
## Steps to create a custom figure
-1. Define a function that returns a [Dash component](https://dash.plotly.com/#open-source-component-libraries).
-This can, but does not need to, be based on code in our pre-defined figure functions in [`vizro.figures`](../API-reference/figure-callables.md).
-2. Decorate it with `@capture("figure")`.
-3. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
-4. The figure should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments
-will not react to dashboard controls such as [`Filter`](filters.md).
-5. Pass your function to the `figure` argument of the [`Figure`][vizro.models.Figure] model.
+1. Define a function that returns a [Dash component](https://dash.plotly.com/#open-source-component-libraries). This can, but does not need to, be based on code in our pre-defined figure functions in [`vizro.figures`](../API-reference/figure-callables.md).
+1. Decorate it with `@capture("figure")`.
+1. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
+1. The figure should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments will not react to dashboard controls such as [`Filter`](filters.md).
+1. Pass your function to the `figure` argument of the [`Figure`][vizro.models.Figure] model.
The following examples can be used as a base to build more sophisticated figures.
## Examples of custom figures
### Custom KPI card
-To change the design or content of our existing KPI (key performance indicator) cards from
-[`vizro.figures`](../API-reference/figure-callables.md), you can do so by following the steps described above.
-For instance, to make a KPI card with the icon positioned on the right side of the title instead of the left,
-copy and paste the [source code of `kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card) and
-adjust the return statement of the function.
+To change the design or content of our existing KPI (key performance indicator) cards from [`vizro.figures`](../API-reference/figure-callables.md), you can do so by following the steps described above.
+
+For instance, to make a KPI card with the icon positioned on the right side of the title instead of the left, copy and paste the [source code of `kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card) and adjust the return statement of the function.
+
!!! example "Custom KPI card"
=== "app.py"
```{.python pycafe-link}
@@ -107,29 +102,26 @@ adjust the return statement of the function.
```
1. Here we decorate our custom figure function with the `@capture("figure")` decorator.
- 2. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
- 3. We adjust the return statement to include the icon on the right side of the title. This is achieved by swapping the order of the `html.H2` and `html.P` compared to the original `kpi_card`.
- 4. This creates a [`layout`](layouts.md) with four rows and columns. The KPI cards are positioned in the first two cells, while the remaining cells are empty.
- 5. For more information, refer to the API reference for the [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card).
- 6. Our custom figure function `custom_kpi_card` now needs to be passed on to the `vm.Figure`.
+ 1. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
+ 1. We adjust the return statement to include the icon on the right side of the title. This is achieved by swapping the order of the `html.H2` and `html.P` compared to the original `kpi_card`.
+ 1. This creates a [`layout`](layouts.md) with four rows and columns. The KPI cards are positioned in the first two cells, while the remaining cells are empty.
+ 1. For more information, refer to the API reference for the [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card).
+ 1. Our custom figure function `custom_kpi_card` now needs to be passed on to the `vm.Figure`.
=== "app.yaml"
- ```yaml
- # Custom figures are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomKPI]][CustomKPI]
+ Custom figures are currently only possible via Python configuration.
- [CustomKPI]: ../../assets/user_guides/figure/custom_kpi.png
+ === "Result"
+ [![CustomKPI]][customkpi]
### Dynamic HTML header
-You can create a custom figure for any [Dash component](https://dash.plotly.com/#open-source-component-libraries).
-Below is an example of a custom figure that returns a `html.H2` component that dynamically updates based on the selected
-name from a filter.
+
+You can create a custom figure for any [Dash component](https://dash.plotly.com/#open-source-component-libraries). Below is an example of a custom figure that returns a `html.H2` component that dynamically updates based on the selected name from a filter.
+
!!! example "Dynamic HTML header"
=== "app.py"
```{.python pycafe-link}
@@ -159,27 +151,24 @@ name from a filter.
```
1. Here we decorate our custom figure function with the `@capture("figure")` decorator.
- 2. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
- 3. We return a `html.H2` component that dynamically updates based on the selected name from the filter.
- 4. Our custom figure function `dynamic_html_header` now needs to be passed on to the `vm.Figure`.
+ 1. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
+ 1. We return a `html.H2` component that dynamically updates based on the selected name from the filter.
+ 1. Our custom figure function `dynamic_html_header` now needs to be passed on to the `vm.Figure`.
=== "app.yaml"
- ```yaml
- # Custom figures are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomHTML]][CustomHTML]
+ Custom figures are currently only possible via Python configuration.
- [CustomHTML]: ../../assets/user_guides/figure/custom_html.png
+ === "Result"
+ [![CustomHTML]][customhtml]
-
### Dynamic number of cards
-The example below shows how to create multiple cards created from a `pandas.DataFrame` where the
-number of cards displayed dynamically adjusts based on a `vm.Parameter`.
+
+The example below shows how to create multiple cards created from a `pandas.DataFrame` where the number of cards displayed dynamically adjusts based on a `vm.Parameter`.
+
!!! example "Dynamic number of cards"
=== "app.py"
```py
@@ -239,40 +228,39 @@ number of cards displayed dynamically adjusts based on a `vm.Parameter`.
```
1. Here we decorate our custom figure function with the `@capture("figure")` decorator.
- 2. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
- 3. Our decorated figure function `multiple_cards` now needs to be passed on to the `vm.Figure`.
- 4. We add a [`vm.Parameter`](parameters.md) to dynamically adjust the number of cards displayed.
- The parameter targets the `n_rows` argument of the `multiple_cards` function, determining the number of rows
- taken from the data.
+ 1. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
+ 1. Our decorated figure function `multiple_cards` now needs to be passed on to the `vm.Figure`.
+ 1. We add a [`vm.Parameter`](parameters.md) to dynamically adjust the number of cards displayed. The parameter targets the `n_rows` argument of the `multiple_cards` function, determining the number of rows taken from the data.
Run and edit this code in PyCafe
=== "styling.css"
```css
.multiple-cards-container {
- display: flex;
- flex-wrap: wrap;
- gap: 12px;
+ display: flex;
+ flex-wrap: wrap;
+ gap: 12px;
}
.figure-container {
- height: unset;
- width: unset;
+ height: unset;
+ width: unset;
}
.figure-container .card {
- height: 210px;
- width: 240px;
+ height: 210px;
+ width: 240px;
}
```
- === "app.yaml"
- ```yaml
- # Custom figures are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomFigure]][CustomFigure]
- [CustomFigure]: ../../assets/user_guides/figure/custom_multiple_cards.png
+ === "app.yaml"
+ Custom figures are currently only possible via Python configuration.
+ === "Result"
+ [![CustomFigure]][customfigure]
+
+[customfigure]: ../../assets/user_guides/figure/custom_multiple_cards.png
+[customhtml]: ../../assets/user_guides/figure/custom_html.png
+[customkpi]: ../../assets/user_guides/figure/custom_kpi.png
diff --git a/vizro-core/docs/pages/user-guides/custom-tables.md b/vizro-core/docs/pages/user-guides/custom-tables.md
index e990cfbb0..42748820b 100644
--- a/vizro-core/docs/pages/user-guides/custom-tables.md
+++ b/vizro-core/docs/pages/user-guides/custom-tables.md
@@ -1,21 +1,18 @@
# How to create custom Dash AG Grids and Dash DataTables
-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.
+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.
-The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] model accept the `figure` argument, where you can enter
-_any_ [`dash_ag_grid`][vizro.tables.dash_ag_grid] or [`dash_data_table`][vizro.tables.dash_data_table] chart as explained in the [user guide on tables](table.md).
+The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] model accept the `figure` argument, where you can enter _any_ [`dash_ag_grid`][vizro.tables.dash_ag_grid] or [`dash_data_table`][vizro.tables.dash_data_table] chart as explained in the [user guide on tables](table.md).
One reason could be that you want to create a table/grid that requires computations that can be controlled by parameters (see the example below).
### Steps to create a custom table
1. Define a function that returns a `dash_ag_grid.AgGrid` or `dash_table.DataTable` object.
-2. Decorate it with `@capture("ag_grid")` or `@capture("table")`.
-3. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
-4. The table should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments
-will not react to dashboard controls such as [`Filter`](filters.md).
-5. Pass your function to the `figure` argument of the [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid] model.
+1. Decorate it with `@capture("ag_grid")` or `@capture("table")`.
+1. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
+1. The table should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments will not react to dashboard controls such as [`Filter`](filters.md).
+1. Pass your function to the `figure` argument of the [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid] model.
The following examples show a possible version of a custom table. In this case the argument `chosen_columns` was added, which you can control with a parameter:
@@ -70,14 +67,12 @@ The following examples show a possible version of a custom table. In this case t
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
- ```yaml
- # Custom tables are currently only possible via Python configuration
- ```
- === "Result"
- [![Table3]][Table3]
+ Custom tables are currently only possible via Python configuration.
- [Table3]: ../../assets/user_guides/table/custom_table.png
+ === "Result"
+ [![Table3]][table3]
??? example "Custom Dash AgGrid"
=== "app.py"
@@ -136,11 +131,12 @@ The following examples show a possible version of a custom table. In this case t
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
- ```yaml
- # Custom Ag Grids are currently only possible via Python configuration
- ```
+ Custom Ag Grids are currently only possible via Python configuration.
+
=== "Result"
- [![GridCustom]][GridCustom]
+ [![GridCustom]][gridcustom]
- [GridCustom]: ../../assets/user_guides/table/custom_grid.png
+[gridcustom]: ../../assets/user_guides/table/custom_grid.png
+[table3]: ../../assets/user_guides/table/custom_table.png
diff --git a/vizro-core/docs/pages/user-guides/dashboard.md b/vizro-core/docs/pages/user-guides/dashboard.md
index 0b37e03fa..244f65256 100644
--- a/vizro-core/docs/pages/user-guides/dashboard.md
+++ b/vizro-core/docs/pages/user-guides/dashboard.md
@@ -1,16 +1,15 @@
# How to create a dashboard
-This guide shows you how to configure and call a [`Dashboard`][vizro.models.Dashboard] using either
-pydantic models, Python dictionaries, YAML, or JSON.
+
+This guide shows you how to configure and call a [`Dashboard`][vizro.models.Dashboard] using either pydantic models, Python dictionaries, YAML, or JSON.
To create a dashboard:
1. Choose one of the possible configuration syntaxes
-2. Create your `pages`, see our [guide on Pages](pages.md)
-3. (optional) Choose a `theme`, see our [guide on Themes](themes.md)
-4. (optional) Customize your `navigation`, see our [guide on Navigation](navigation.md)
-5. (optional) Set a `title` for your dashboard
-6. Add your `dashboard` to the `build` call of Vizro
-
+1. Create your `pages`, see our [guide on Pages](pages.md)
+1. (optional) Choose a `theme`, see our [guide on Themes](themes.md)
+1. (optional) Customize your `navigation`, see our [guide on Navigation](navigation.md)
+1. (optional) Set a `title` for your dashboard
+1. Add your `dashboard` to the `build` call of Vizro
## Use dashboard configuration options
@@ -37,6 +36,7 @@ To create a dashboard:
Vizro().build(dashboard).run()
```
+
=== "app.py - Python dict"
```py
import vizro.plotly.express as px
@@ -77,6 +77,7 @@ To create a dashboard:
Vizro().build(dashboard).run()
```
+
=== "dashboard.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -101,50 +102,49 @@ To create a dashboard:
type: filter
title: My first dashboard
```
+
=== "dashboard.json"
```json
{
- "pages": [
+ "pages": [
+ {
+ "components": [
+ {
+ "figure": {
+ "_target_": "scatter",
+ "color": "species",
+ "data_frame": "iris",
+ "x": "sepal_length",
+ "y": "petal_width"
+ },
+ "type": "graph"
+ },
{
- "components": [
- {
- "figure": {
- "_target_": "scatter",
- "color": "species",
- "data_frame": "iris",
- "x": "sepal_length",
- "y": "petal_width"
- },
- "type": "graph"
- },
- {
- "figure": {
- "_target_": "histogram",
- "color": "species",
- "data_frame": "iris",
- "x": "sepal_width",
- },
- "type": "graph"
- }
- ],
- "controls": [
- {
- "column": "species",
- "type": "filter"
- }
- ],
- "title": "My first dashboard"
+ "figure": {
+ "_target_": "histogram",
+ "color": "species",
+ "data_frame": "iris",
+ "x": "sepal_width"
+ },
+ "type": "graph"
}
- ]
+ ],
+ "controls": [
+ {
+ "column": "species",
+ "type": "filter"
+ }
+ ],
+ "title": "My first dashboard"
+ }
+ ]
}
```
- === "Result"
- [![Dashboard]][Dashboard]
- [Dashboard]: ../../assets/user_guides/dashboard/dashboard.png
+ === "Result"
+ [![Dashboard]][dashboard]
!!! note "Extra `.py` files for `yaml` and `json` required"
-
Note that in the `yaml` and `json` example an extra `.py` is required to register the data and parse the yaml/json configuration.
=== "app.py for yaml"
@@ -164,6 +164,7 @@ To create a dashboard:
Vizro().build(dashboard).run()
```
+
=== "app.py for json"
```py
import json
@@ -187,7 +188,6 @@ After running the dashboard, you can access the dashboard via `localhost:8050`.
If supplied, the `title` of the [`Dashboard`][vizro.models.Dashboard] displays a heading at the top of every page.
-
## Add a dashboard logo
Vizro will [automatically incorporate the dashboard logo](assets.md/#add-a-logo-image) in the top-left corner of each page if an image named `logo.` is present within the assets folder.
@@ -196,11 +196,10 @@ Vizro will [automatically incorporate the dashboard logo](assets.md/#add-a-logo-
## Browser title
-The [website icon](assets.md/#change-the-favicon), Dashboard `title` (if supplied) and [Page `title`][vizro.models.Page] are displayed in the browser's
-title bar. For example, if your Dashboard `title` is "Vizro Demo" and the Page `title` is "Homepage", then the title in the browser tab will be "Vizro Demo: Homepage".
+The [website icon](assets.md/#change-the-favicon), Dashboard `title` (if supplied) and [Page `title`][vizro.models.Page] are displayed in the browser's title bar. For example, if your Dashboard `title` is "Vizro Demo" and the Page `title` is "Homepage", then the title in the browser tab will be "Vizro Demo: Homepage".
## Meta tags for social media
-Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat
-clients. The preview includes the `URL`, `title`, plus an [image](assets.md/#include-a-meta-tags-image) and
-[Page `description`][vizro.models.Page] (if supplied). To see an example, try sharing an example from the [Vizro examples gallery](https://vizro.mckinsey.com/).
+Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat clients. The preview includes the `URL`, `title`, plus an [image](assets.md/#include-a-meta-tags-image) and [Page `description`][vizro.models.Page] (if supplied). To see an example, try sharing an example from the [Vizro examples gallery](https://vizro.mckinsey.com/).
+
+[dashboard]: ../../assets/user_guides/dashboard/dashboard.png
diff --git a/vizro-core/docs/pages/user-guides/data.md b/vizro-core/docs/pages/user-guides/data.md
index 51bf84b97..d19b8aafb 100644
--- a/vizro-core/docs/pages/user-guides/data.md
+++ b/vizro-core/docs/pages/user-guides/data.md
@@ -2,11 +2,12 @@
Vizro supports two different types of data:
-* [Static data](#static-data): pandas DataFrame. This is the simplest method and best to use if you do not need the more advanced functionality of dynamic data.
-* [Dynamic data](#dynamic-data): function that returns a pandas DataFrame. This is a bit more complex to understand but has more advanced functionality such as the ability to refresh data while the dashboard is running.
+- [Static data](#static-data): pandas DataFrame. This is the simplest method and best to use if you do not need the more advanced functionality of dynamic data.
+- [Dynamic data](#dynamic-data): function that returns a pandas DataFrame. This is a bit more complex to understand but has more advanced functionality such as the ability to refresh data while the dashboard is running.
The following flowchart shows what you need to consider when choosing how to set up your data.
-``` mermaid
+
+```mermaid
graph TD
refresh["`Do you need your data to refresh while the dashboard is running?`"]
specification["`Do you need to specify your dashboard through a configuration language like YAML?`"]
@@ -27,11 +28,10 @@ graph TD
```
??? note "Static vs. dynamic data comparison"
-
This table gives a full comparison between static and dynamic data. Do not worry if you do not yet understand everything in it; it will become clearer after reading more about [static data](#static-data) and [dynamic data](#dynamic-data)!
| | Static | Dynamic |
- |---------------------------------------------------------------|------------------|------------------------------------------|
+ | ------------------------------------------------------------- | ---------------- | ---------------------------------------- |
| Required Python type | pandas DataFrame | Function that returns a pandas DataFrame |
| Can be supplied directly in `data_frame` argument of `figure` | Yes | No |
| Can be referenced by name after adding to data manager | Yes | Yes |
@@ -73,14 +73,13 @@ The below example uses the Iris data saved to a file `iris.csv` in the same dire
```
1. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
- === "Result"
- [![DataBasic]][DataBasic]
- [DataBasic]: ../../assets/user_guides/data/data_pandas_dataframe.png
+ === "Result"
+ [![DataBasic]][databasic]
The [`Graph`][vizro.models.Graph], [`AgGrid`][vizro.models.AgGrid] and [`Table`][vizro.models.Table] models all have an argument called `figure`. This accepts a function (in the above example, `px.scatter`) that takes a pandas DataFrame as its first argument. The name of this argument is always `data_frame`. When configuring the dashboard using Python, it is optional to give the name of the argument: if you like, you could write `data_frame=iris` instead of `iris`.
-!!! note
+!!! note
With static data, once the dashboard is running, the data shown in the dashboard cannot change even if the source data in `iris.csv` changes. The code `iris = pd.read_csv("iris.csv")` is only executed once when the dashboard is first started. If you would like changes to source data to flow through to the dashboard then you must use [dynamic data](#dynamic-data).
### Reference by name
@@ -107,27 +106,27 @@ If you would like to specify your dashboard configuration through YAML then you
```
1. `"iris"` is the name of a data source added to the data manager. This data is a pandas DataFrame created by reading from the CSV file `iris.csv`.
+
=== "dashboard.yaml"
```yaml
pages:
- - components:
- - figure:
+ - components:
+ figure:
_target_: box
data_frame: iris # (1)!
x: species
y: petal_width
color: species
type: graph
- title: Static data example
+ title: Static data example
```
1. Refer to the `"iris"` data source in the data manager.
- === "Result"
- [![DataBasic]][DataBasic]
- [DataBasic]: ../../assets/user_guides/data/data_pandas_dataframe.png
+ === "Result"
+ [![DataBasic]][databasic]
-It is also possible to refer to a named data source using the Python API: `px.scatter("iris", ...)` or `px.scatter(data_frame="iris", ...)` would work if the `"iris"` data source has been registered in the data manager.
+It is also possible to refer to a named data source using the Python API: `px.scatter("iris", ...)` or `px.scatter(data_frame="iris", ...)` would work if the `"iris"` data source has been registered in the data manager.
## Dynamic data
@@ -166,14 +165,12 @@ The example below shows how data is fetched dynamically every time the page is r
```
1. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
- 2. To demonstrate that dynamic data can change when the page is refreshed, select 50 points at random. This simulates what would happen if your file `iris.csv` were constantly changing.
- 3. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()`; doing so would result in static data that cannot be reloaded.
- 4. Dynamic data is referenced by the name of the data source `"iris"`.
+ 1. To demonstrate that dynamic data can change when the page is refreshed, select 50 points at random. This simulates what would happen if your file `iris.csv` were constantly changing.
+ 1. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()`; doing so would result in static data that cannot be reloaded.
+ 1. Dynamic data is referenced by the name of the data source `"iris"`.
=== "Result"
- [![DynamicData]][DynamicData]
-
- [DynamicData]: ../../assets/user_guides/data/dynamic_data.gif
+ [![DynamicData]][dynamicdata]
Since dynamic data sources must always be added to the data manager and referenced by name, they may be used in YAML configuration [exactly the same way as for static data sources](#reference-by-name).
@@ -184,10 +181,10 @@ By default, a dynamic data function executes every time the dashboard is refresh
The Vizro data manager has a server-side caching mechanism to help solve this. Vizro's cache uses [Flask-Caching](https://flask-caching.readthedocs.io/en/latest/), which supports a number of possible cache backends and [configuration options](https://flask-caching.readthedocs.io/en/latest/#configuring-flask-caching). By default, the cache is turned off.
+
In a development environment the easiest way to enable caching is to use a [simple memory cache](https://cachelib.readthedocs.io/en/stable/simple/) with the default configuration options. This is achieved by adding one line to the above example to set `data_manager.cache`:
!!! example "Simple cache with default timeout of 5 minutes"
-
```py hl_lines="13"
from flask_caching import Cache
from vizro import Vizro
@@ -225,7 +222,6 @@ data_manager.cache = Cache(config={"CACHE_TYPE": "SimpleCache", "CACHE_DEFAULT_T
```
!!! warning
-
Simple cache exists purely for single-process development purposes and is not intended to be used in production. If you deploy with multiple workers, [for example with Gunicorn](run.md/#gunicorn), then you should use a production-ready cache backend. All of Flask-Caching's [built-in backends](https://flask-caching.readthedocs.io/en/latest/#built-in-cache-backends) other than `SimpleCache` are suitable for production. In particular, you might like to use [`FileSystemCache`](https://cachelib.readthedocs.io/en/stable/file/) or [`RedisCache`](https://cachelib.readthedocs.io/en/stable/redis/):
```py title="Production-ready caches"
@@ -239,7 +235,9 @@ data_manager.cache = Cache(config={"CACHE_TYPE": "SimpleCache", "CACHE_DEFAULT_T
Since Flask-Caching relies on [`pickle`](https://docs.python.org/3/library/pickle.html), which can execute arbitrary code during unpickling, you should not cache data from untrusted sources. Doing so [could be unsafe](https://github.com/pallets-eco/flask-caching/pull/209).
Note that when a production-ready cache backend is used, the cache is persisted beyond the Vizro process and is not cleared by restarting your server. To clear the cache then you must do so manually, for example, if you use `FileSystemCache` then you would delete your `cache` directory. Persisting the cache can also be useful for development purposes when handling data that takes a long time to load: even if you do not need the data to refresh while your dashboard is running, it can speed up your development loop to use dynamic data with a cache that is persisted between repeated runs of Vizro.
+
+
#### Set timeouts
You can change the timeout of the cache independently for each dynamic data source in the data manager using the `timeout` setting (measured in seconds). A `timeout` of 0 indicates that the cache does not expire. This is effectively the same as using [static data](#static-data).
@@ -278,8 +276,8 @@ In general, a parametrized dynamic data source should always return a pandas Dat
To add a parameter to control a dynamic data source, do the following:
1. add the appropriate argument to your dynamic data function and specify a default value for the argument.
-2. give an `id` to all components that have the data source you wish to alter through a parameter.
-3. [add a parameter](parameters.md) with `targets` of the form `.data_frame.` and a suitable [selector](selectors.md).
+1. give an `id` to all components that have the data source you wish to alter through a parameter.
+1. [add a parameter](parameters.md) with `targets` of the form `.data_frame.` and a suitable [selector](selectors.md).
For example, let us extend the [dynamic data example](#dynamic-data) above into an example of how parametrized dynamic data works. The `load_iris_data` can take an argument `number_of_points` controlled from the dashboard with a [`Slider`][vizro.models.Slider].
@@ -318,21 +316,18 @@ For example, let us extend the [dynamic data example](#dynamic-data) above into
```
1. `load_iris_data` takes a single argument, `number_of_points`, with a default value of 10.
- 2. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
- 3. Sample points at random, where `number_of_points` gives the number of points selected.
- 4. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()` or `load_iris_data(number_of_points=...)`; doing so would result in static data that cannot be reloaded.
- 5. Give the `vm.Graph` component `id="graph"` so that the `vm.Parameter` can target it. Dynamic data is referenced by the name of the data source `"iris"`.
- 6. Create a `vm.Parameter` to target the `number_of_points` argument for the `data_frame` used in `graph`.
+ 1. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
+ 1. Sample points at random, where `number_of_points` gives the number of points selected.
+ 1. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()` or `load_iris_data(number_of_points=...)`; doing so would result in static data that cannot be reloaded.
+ 1. Give the `vm.Graph` component `id="graph"` so that the `vm.Parameter` can target it. Dynamic data is referenced by the name of the data source `"iris"`.
+ 1. Create a `vm.Parameter` to target the `number_of_points` argument for the `data_frame` used in `graph`.
=== "Result"
- [![ParametrizedDynamicData]][ParametrizedDynamicData]
-
- [ParametrizedDynamicData]: ../../assets/user_guides/data/parametrized_dynamic_data.gif
+ [![ParametrizedDynamicData]][parametrizeddynamicdata]
Parametrized data loading is compatible with [caching](#configure-cache). The cache uses [memoization](https://flask-caching.readthedocs.io/en/latest/#memoization), so that the dynamic data function's arguments are included in the cache key. This means that `load_iris_data(number_of_points=10)` is cached independently of `load_iris_data(number_of_points=20)`.
!!! warning
-
You should always [treat the content of user input as untrusted](https://community.plotly.com/t/writing-secure-dash-apps-community-thread/54619). For example, you should not expose a filepath to load without passing it through a function like [`werkzeug.utils.secure_filename`](https://werkzeug.palletsprojects.com/en/3.0.x/utils/#werkzeug.utils.secure_filename), or you might enable arbitrary access to files on your server.
You cannot pass [nested parameters](parameters.md#nested-parameters) to dynamic data. You can only target the top-level arguments of the data loading function, not the nested keys in a dictionary.
@@ -354,7 +349,6 @@ When the page is refreshed, the behavior of a dynamic filter is as follows:
For example, let us add two filters to the [dynamic data example](#dynamic-data) above:
!!! example "Dynamic filters"
-
```py hl_lines="10 20 21"
from vizro import Vizro
import pandas as pd
@@ -386,8 +380,8 @@ For example, let us add two filters to the [dynamic data example](#dynamic-data)
```
1. We sample only 5 rather than 50 points so that changes to the available values in the filtered columns are more apparent when the page is refreshed.
- 2. This filter implicitly controls the dynamic data source `"iris"`, which supplies the `data_frame` to the targeted `vm.Graph`. On page refresh, Vizro reloads this data, finds all the unique values in the `"species"` column and sets the categorical selector's `options` accordingly.
- 3. Similarly, on page refresh, Vizro finds the minimum and maximum values of the `"sepal_length"` column in the reloaded data and sets new `min` and `max` values for the numerical selector accordingly.
+ 1. This filter implicitly controls the dynamic data source `"iris"`, which supplies the `data_frame` to the targeted `vm.Graph`. On page refresh, Vizro reloads this data, finds all the unique values in the `"species"` column and sets the categorical selector's `options` accordingly.
+ 1. Similarly, on page refresh, Vizro finds the minimum and maximum values of the `"sepal_length"` column in the reloaded data and sets new `min` and `max` values for the numerical selector accordingly.
Consider a filter that depends on dynamic data, where you do **not** want the available values to change when the dynamic data changes. You should manually specify the `selector`'s `options` field (categorical selector) or `min` and `max` fields (numerical selector). In the above example, this could be achieved as follows:
@@ -409,10 +403,13 @@ controls = [
When Vizro initially builds a filter that depends on parametrized dynamic data loading, data is loaded using the default argument values. This data is used to:
-* perform initial validation
-* check which data sources contain the specified `column` (unless `targets` is explicitly specified) and
-* find the type of selector to use (unless `selector` is explicitly specified).
+- perform initial validation
+- check which data sources contain the specified `column` (unless `targets` is explicitly specified) and
+- find the type of selector to use (unless `selector` is explicitly specified).
!!! note
-
When the value of a dynamic data parameter is changed by a dashboard user, the data underlying a dynamic filter can change. Currently this change affects page components such as `vm.Graph` but does not affect the available values shown in a dynamic filter, which only update on page refresh. This functionality will be coming soon!
+
+[databasic]: ../../assets/user_guides/data/data_pandas_dataframe.png
+[dynamicdata]: ../../assets/user_guides/data/dynamic_data.gif
+[parametrizeddynamicdata]: ../../assets/user_guides/data/parametrized_dynamic_data.gif
diff --git a/vizro-core/docs/pages/user-guides/extensions.md b/vizro-core/docs/pages/user-guides/extensions.md
index 2c7efc9ac..74a740448 100644
--- a/vizro-core/docs/pages/user-guides/extensions.md
+++ b/vizro-core/docs/pages/user-guides/extensions.md
@@ -2,64 +2,49 @@
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).
+- **[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.
+- **[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.
-* **[CSS customizations](#css-customizations)**. You can add custom CSS to any Vizro dashboard, enabling users to deviate from the default styling and create a unique look and feel for their dashboard.
-
-* **[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
+- **[CSS customizations](#css-customizations)**. You can add custom CSS to any Vizro dashboard, enabling users to deviate from the default styling and create a unique look and feel for their dashboard.
+- **[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
-
+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)).
+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.
-
+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).
+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
+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:
+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
@@ -93,14 +78,12 @@ enabling an interaction between data points in a scatter plot and the content of
## CSS customizations
-Vizro is opinionated about visual formatting, and some elements, such as the layout of the navigation and controls,
-are fixed. You can customize some settings such as background colors, fonts, and other styles via CSS overrides.
+Vizro is opinionated about visual formatting, and some elements, such as the layout of the navigation and controls, are fixed. You can customize some settings such as background colors, fonts, and other styles via CSS overrides.
For more information, see our documentation on [customizing CSS](custom-css.md)
## 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
+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)
diff --git a/vizro-core/docs/pages/user-guides/figure.md b/vizro-core/docs/pages/user-guides/figure.md
index 0589fad3b..03bfa412a 100644
--- a/vizro-core/docs/pages/user-guides/figure.md
+++ b/vizro-core/docs/pages/user-guides/figure.md
@@ -1,26 +1,19 @@
# How to use figures
-This guide shows you how to add any [Dash component](https://dash.plotly.com/#open-source-component-libraries) that needs to be reactive to [filter](filters.md) and [parameter](parameters.md) controls.
-If you want to add a static Dash component to your page, use [custom components](custom-components.md) instead.
+This guide shows you how to add any [Dash component](https://dash.plotly.com/#open-source-component-libraries) that needs to be reactive to [filter](filters.md) and [parameter](parameters.md) controls. If you want to add a static Dash component to your page, use [custom components](custom-components.md) instead.
-[`Figure`][vizro.models.Figure] provides a flexible foundation for all types of reactive Dash components in Vizro.
-The [`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] and [`AgGrid`][vizro.models.AgGrid] components are
-specific implementations of `Figure`. They serve as intuitive shortcuts, embedding behaviors and interactions specific
-to their purposes.
+[`Figure`][vizro.models.Figure] provides a flexible foundation for all types of reactive Dash components in Vizro. The [`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] and [`AgGrid`][vizro.models.AgGrid] components are specific implementations of `Figure`. They serve as intuitive shortcuts, embedding behaviors and interactions specific to their purposes.
-If these more specific models already achieve what you need then they should be used in preference to
-the more generic `Figure`. Remember that it is possible to supply [custom charts](custom-charts.md) to `Graph`
-and [custom tables](custom-tables.md) to `Table`.
+If these more specific models already achieve what you need then they should be used in preference to the more generic `Figure`. Remember that it is possible to supply [custom charts](custom-charts.md) to `Graph` and [custom tables](custom-tables.md) to `Table`.
-There are already a few figure functions you can reuse, see the section on [KPI cards](#key-performance-indicator-kpi-cards)
-for more details:
+There are already a few figure functions you can reuse, see the section on [KPI cards](#key-performance-indicator-kpi-cards) for more details:
- [`kpi_card`][vizro.figures.kpi_card]
- [`kpi_card_reference`][vizro.figures.kpi_card_reference]
The following flowchart shows what you need to consider when choosing which model to use:
-``` mermaid
+```mermaid
graph TD
first["`Does your desired component exist in Vizro, e.g. Graph, Table or AgGrid?`"]
specific-component([Use the specific component])
@@ -40,14 +33,12 @@ graph TD
classDef clickable color:#4051b5;
```
-
To add a `Figure` to your page:
1. Add the `Figure` model to the components argument of the [Page][vizro.models.Page] model.
-2. Use an existing figure function from [`vizro.figures`](../API-reference/figure-callables.md) and pass it to the `figure` argument of the `Figure` model.
+1. Use an existing figure function from [`vizro.figures`](../API-reference/figure-callables.md) and pass it to the `figure` argument of the `Figure` model.
!!! example "Use existing figure functions"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -99,40 +90,25 @@ To add a `Figure` to your page:
selector:
type: radio_items
layout:
- grid:
- [
- [0, -1, -1, -1],
- [-1, -1, -1, -1],
- [-1, -1, -1, -1],
- [-1, -1, -1, -1],
- [-1, -1, -1, -1],
- ]
+ grid: [[0, -1, -1, -1], [-1, -1, -1, -1], [-1, -1, -1, -1], [-1, -1, -1, -1],
+ [-1, -1, -1, -1]]
title: KPI card
```
- === "Result"
- [![Figure]][Figure]
-
- [Figure]: ../../assets/user_guides/figure/figure.png
+ === "Result"
+ [![Figure]][figure]
### Key Performance Indicator (KPI) cards
-A KPI card is a dynamic card that can display a single value, but optionally, can also include a title, icon, and reference value.
-It is a common visual component to display key metrics in a dashboard. Vizro supports two pre-defined KPI card functions:
-- [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card): A KPI card that shows a single value found
-by performing an aggregation function (by default, `sum`) over a specified column.
-Required arguments are `data_frame` and `value_column`.
+A KPI card is a dynamic card that can display a single value, but optionally, can also include a title, icon, and reference value. It is a common visual component to display key metrics in a dashboard. Vizro supports two pre-defined KPI card functions:
-- [`kpi_card_with_reference`](../API-reference/figure-callables.md#vizro.figures.kpi_card_reference): A KPI card that shows a single value
-and a delta comparison to a reference value found by performing an aggregation function (by default, `sum`) over the specified columns.
-Required arguments are `data_frame`, `value_column` and `reference_column`.
+- [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card): A KPI card that shows a single value found by performing an aggregation function (by default, `sum`) over a specified column. Required arguments are `data_frame` and `value_column`.
-As described in the [API reference](../API-reference/figure-callables.md) and illustrated in the below example, these
-functions have several arguments to customize your KPI cards. If you require a level of customization that is not
-possible with the built-in functions then you can create a [custom figure](custom-figures.md).
+- [`kpi_card_with_reference`](../API-reference/figure-callables.md#vizro.figures.kpi_card_reference): A KPI card that shows a single value and a delta comparison to a reference value found by performing an aggregation function (by default, `sum`) over the specified columns. Required arguments are `data_frame`, `value_column` and `reference_column`.
-!!! example "KPI card variations"
+As described in the [API reference](../API-reference/figure-callables.md) and illustrated in the below example, these functions have several arguments to customize your KPI cards. If you require a level of customization that cannot be done with the built-in functions then you can create a [custom figure](custom-figures.md).
+!!! example "KPI card variations"
=== "app.py"
```{.python pycafe-link}
import pandas as pd
@@ -258,8 +234,8 @@ possible with the built-in functions then you can create a [custom figure](custo
value_column: Actual
reference_column: Reference
title: KPI reference with formatting
- value_format: "{value:.2f}€"
- reference_format: "{delta:+.2f}€ vs. last year ({reference:.2f}€)"
+ value_format: '{value:.2f}€'
+ reference_format: '{delta:+.2f}€ vs. last year ({reference:.2f}€)'
type: figure
- figure:
_target_: kpi_card_reference
@@ -276,7 +252,9 @@ possible with the built-in functions then you can create a [custom figure](custo
grid: [[0, 1, 2, 3], [4, 5, 6, 7], [-1, -1, -1, -1], [-1, -1, -1, -1]]
title: KPI cards
```
+
=== "Result"
- [![KPICards]][KPICards]
+ [![KPICards]][kpicards]
- [KPICards]: ../../assets/user_guides/figure/kpi_cards.png
+[figure]: ../../assets/user_guides/figure/figure.png
+[kpicards]: ../../assets/user_guides/figure/kpi_cards.png
diff --git a/vizro-core/docs/pages/user-guides/filters.md b/vizro-core/docs/pages/user-guides/filters.md
index bc3649178..8228ecbe7 100644
--- a/vizro-core/docs/pages/user-guides/filters.md
+++ b/vizro-core/docs/pages/user-guides/filters.md
@@ -2,8 +2,7 @@
This guide shows you how to add filters to your dashboard. One main way to interact with the charts/components on your page is by filtering the underlying data. A filter selects a subset of rows of a component's underlying DataFrame which alters the appearance of that component on the page.
-The [`Page`][vizro.models.Page] model accepts the `controls` argument, where you can enter a [`Filter`][vizro.models.Filter] model.
-This model enables the automatic creation of [selectors](selectors.md) (for example, `Dropdown` or `RangeSlider`) that operate on the charts/components on the screen.
+The [`Page`][vizro.models.Page] model accepts the `controls` argument, where you can enter a [`Filter`][vizro.models.Filter] model. This model enables the automatic creation of [selectors](selectors.md) (for example, `Dropdown` or `RangeSlider`) that operate on the charts/components on the screen.
By default, filters that control components with [dynamic data](data.md#dynamic-data) are [dynamically updated](data.md#filters) when the underlying data changes while the dashboard is running.
@@ -12,7 +11,7 @@ By default, filters that control components with [dynamic data](data.md#dynamic-
To add a filter to your page, do the following:
1. add the [`Filter`][vizro.models.Filter] model into the `controls` argument of the [`Page`][vizro.models.Page] model
-2. configure the `column` argument, which denotes the target column to be filtered
+1. configure the `column` argument, which denotes the target column to be filtered
You can also set `targets` to specify which components on the page the filter should apply to. If this is not explicitly set then `targets` defaults to all components on the page whose data source includes `column`.
@@ -39,6 +38,7 @@ You can also set `targets` to specify which components on the page the filter sh
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -57,17 +57,15 @@ You can also set `targets` to specify which components on the page the filter sh
type: filter
title: My first page
```
- === "Result"
- [![Filter]][Filter]
-
- [Filter]: ../../assets/user_guides/control/control1.png
+ === "Result"
+ [![Filter]][filter]
The selector is configured automatically based on the target column type data as follows:
- - Categorical data uses [`vm.Dropdown(multi=True)`][vizro.models.Dropdown] where `options` is the set of unique values found in `column` across all the data sources of components in `targets`.
- - [Numerical data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_numeric_dtype.html) uses [`vm.RangeSlider`][vizro.models.RangeSlider] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`.
- - [Temporal data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_datetime64_any_dtype.html) uses [`vm.DatePicker(range=True)`][vizro.models.DatePicker] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`. A column can be converted to this type with [pandas.to_datetime](https://pandas.pydata.org/docs/reference/api/pandas.to_datetime.html).
+- Categorical data uses [`vm.Dropdown(multi=True)`][vizro.models.Dropdown] where `options` is the set of unique values found in `column` across all the data sources of components in `targets`.
+- [Numerical data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_numeric_dtype.html) uses [`vm.RangeSlider`][vizro.models.RangeSlider] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`.
+- [Temporal data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_datetime64_any_dtype.html) uses [`vm.DatePicker(range=True)`][vizro.models.DatePicker] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`. A column can be converted to this type with [pandas.to_datetime](https://pandas.pydata.org/docs/reference/api/pandas.to_datetime.html).
The following example demonstrates these default selector types.
@@ -107,6 +105,7 @@ The following example demonstrates these default selector types.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -129,15 +128,13 @@ The following example demonstrates these default selector types.
type: filter
title: My first page
```
- === "Result"
- [![Filter]][Filter]
- [Filter]: ../../assets/user_guides/selectors/default_filter_selectors.png
+ === "Result"
+ [![Filter]][filter]
## Change selector
-If you want to have a different selector for your filter, you can give the `selector` argument of the [`Filter`][vizro.models.Filter] a different selector model.
-Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropdown`][vizro.models.Dropdown], [`RadioItems`][vizro.models.RadioItems], [`RangeSlider`][vizro.models.RangeSlider], [`Slider`][vizro.models.Slider], and [`DatePicker`][vizro.models.DatePicker].
+If you want to have a different selector for your filter, you can give the `selector` argument of the [`Filter`][vizro.models.Filter] a different selector model. Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropdown`][vizro.models.Dropdown], [`RadioItems`][vizro.models.RadioItems], [`RangeSlider`][vizro.models.RangeSlider], [`Slider`][vizro.models.Slider], and [`DatePicker`][vizro.models.DatePicker].
!!! example "Filter with different selector"
=== "app.py"
@@ -162,6 +159,7 @@ Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropd
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -181,11 +179,9 @@ Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropd
type: filter
title: My first page
```
- === "Result"
-
- [![Selector]][Selector]
- [Selector]: ../../assets/user_guides/control/control2.png
+ === "Result"
+ [![Selector]][selector]
## Further customization
@@ -220,6 +216,7 @@ Below is an advanced example where we only target one page component, and where
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -244,17 +241,19 @@ Below is an advanced example where we only target one page component, and where
controls:
- column: petal_length
targets:
- - scatter_chart
+ - scatter_chart
selector:
step: 1
type: range_slider
type: filter
title: My first page
```
- === "Result"
-
- [![Advanced]][Advanced]
- [Advanced]: ../../assets/user_guides/control/control3.png
+ === "Result"
+ [![Advanced]][advanced]
To further customize selectors, see our [how-to-guide on creating custom components](custom-components.md).
+
+[advanced]: ../../assets/user_guides/control/control3.png
+[filter]: ../../assets/user_guides/control/control1.png
+[selector]: ../../assets/user_guides/control/control2.png
diff --git a/vizro-core/docs/pages/user-guides/graph.md b/vizro-core/docs/pages/user-guides/graph.md
index 36c670997..1c3ffc8bc 100755
--- a/vizro-core/docs/pages/user-guides/graph.md
+++ b/vizro-core/docs/pages/user-guides/graph.md
@@ -6,25 +6,18 @@ The [`Graph`][vizro.models.Graph] model is the most used component in many dashb
To add a [`Graph`][vizro.models.Graph] to your page, do the following:
-1. insert the [`Graph`][vizro.models.Graph] model into the `components` argument of the
-[`Page`][vizro.models.Page] model
-2. enter any of the currently available charts of the open source library [`plotly.express`](https://plotly.com/python/plotly-express/) into the `figure` argument
+1. insert the [`Graph`][vizro.models.Graph] model into the `components` argument of the [`Page`][vizro.models.Page] model
+1. enter any of the currently available charts of the open source library [`plotly.express`](https://plotly.com/python/plotly-express/) into the `figure` argument
!!! note
+ To use the [`plotly.express`](https://plotly.com/python/plotly-express/) chart in a Vizro dashboard, you need to import it as `import vizro.plotly.express as px`. This leaves any of the [`plotly.express`](https://plotly.com/python/plotly-express/) functionality untouched yet enables _direct insertion_ into the [`Graph`][vizro.models.Graph] model _as is_.
- In order to use the [`plotly.express`](https://plotly.com/python/plotly-express/) chart in a Vizro dashboard, you need to import it as `import vizro.plotly.express as px`.
- This leaves any of the [`plotly.express`](https://plotly.com/python/plotly-express/) functionality untouched, but allows _direct insertion_ into the [`Graph`][vizro.models.Graph] model _as is_.
-
- Note also that the `plotly.express` chart needs to have a `data_frame` argument. In case you require a chart without
- a `data_frame` argument (for example, the [`imshow` chart](https://plotly.com/python/imshow/)), refer to our
- [guide on custom charts](custom-charts.md).
-
+ Note also that the `plotly.express` chart needs to have a `data_frame` argument. In case you require a chart without a `data_frame` argument (for example, the [`imshow` chart](https://plotly.com/python/imshow/)), refer to our [guide on custom charts](custom-charts.md).
## Insert Plotly chart
!!! example "Graph"
=== "app.py"
-
```{.python pycafe-link}
import vizro.models as vm
import vizro.plotly.express as px
@@ -47,25 +40,24 @@ To add a [`Graph`][vizro.models.Graph] to your page, do the following:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: scatter_matrix
- color: species
- data_frame: iris
- dimensions: ["sepal_length", "sepal_width", "petal_length", "petal_width"]
- type: graph
- title: My first page
+ - components:
+ - figure:
+ _target_: scatter_matrix
+ color: species
+ data_frame: iris
+ dimensions: [sepal_length, sepal_width, petal_length, petal_width]
+ type: graph
+ title: My first page
```
- === "Result"
- [![Graph]][Graph]
-
- [Graph]: ../../assets/user_guides/components/graph.png
+ === "Result"
+ [![Graph]][graph]
In the Python example we directly inserted the pandas DataFrame `df` into `figure=px.scatter_matrix(df, ...)`. This is [one way to supply data to a chart](data.md#supply-directly). For the YAML version, we [refer to the data source by name](data.md#reference-by-name) as `data_frame: iris`. For a full explanation of the different methods you can use to send data to your dashboard, see [our guide to using data in Vizro](data.md).
@@ -73,31 +65,24 @@ In the Python example we directly inserted the pandas DataFrame `df` into `figur
You will need to create a custom chart if you want to customize the Plotly chart beyond a function call, for example by:
-* using post-update methods like `update_layout`, `update_xaxes`, `update_traces`, or
-* by creating a custom `plotly.graph_objects.Figure()` object and manually adding traces with `add_trace`.
-
-For more details, refer to our [user guide on custom chart](custom-charts.md) and the
-[Plotly documentation on updating figures](https://plotly.com/python/creating-and-updating-figures/).
+- using post-update methods like `update_layout`, `update_xaxes`, `update_traces`, or
+- by creating a custom `plotly.graph_objects.Figure()` object and manually adding traces with `add_trace`.
+For more details, refer to our [user guide on custom chart](custom-charts.md) and the [Plotly documentation on updating figures](https://plotly.com/python/creating-and-updating-figures/).
## Add title, header, and footer
-The [`Graph`][vizro.models.Graph] accepts a `title`, `header` and `footer` argument. This is useful for providing
-context to the data being displayed, or for adding a description of the data.
+The [`Graph`][vizro.models.Graph] accepts a `title`, `header` and `footer` argument. This is useful for context on the data being displayed, or for adding a description of the data.
- **title**: Displayed as an [H3 header](https://dash.plotly.com/dash-html-components/h3), useful for summarizing the main topic or insight of the component.
- **header**: Accepts markdown text, ideal for extra descriptions, subtitles, or detailed data insights.
- **footer**: Accepts markdown text, commonly used for citing data sources, providing information on the last update, or adding disclaimers.
-
!!! note
-
- Although you can directly provide a `title` to the Plotly Express chart, we recommend using `Graph.title` for
- proper alignment with other components on the screen.
+ Although you can directly give a `title` to the Plotly Express chart, we recommend using `Graph.title` for proper alignment with other components on the screen.
!!! example "Formatted Graph"
=== "app.py"
-
```{.python pycafe-link}
import vizro.models as vm
@@ -126,31 +111,34 @@ context to the data being displayed, or for adding a description of the data.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: scatter
- x: sepal_width
- y: sepal_length
- color: species
- data_frame: iris
- title: Relationships between Sepal Width and Sepal Length
- header: |
- Each point in the scatter plot represents one of the 150 iris flowers, with colors indicating their
- types. The Setosa type is easily identifiable by its short and wide sepals.
-
- However, there is still overlap between the Versicolor and Virginica types when considering only sepal
- width and length.
- footer: |
- SOURCE: **Plotly iris data set, 2024**
- type: graph
- title: Formatted Graph
+ - components:
+ - figure:
+ _target_: scatter
+ x: sepal_width
+ y: sepal_length
+ color: species
+ data_frame: iris
+ title: Relationships between Sepal Width and Sepal Length
+ header: |
+ Each point in the scatter plot represents one of the 150 iris flowers, with colors indicating their
+ types. The Setosa type is easily identifiable by its short and wide sepals.
+
+ However, there is still overlap between the Versicolor and Virginica types when considering only sepal
+ width and length.
+ footer: |
+ SOURCE: **Plotly iris data set, 2024**
+ type: graph
+ title: Formatted Graph
```
+
=== "Result"
- [![FormattedGraph]][FormattedGraph]
+ [![FormattedGraph]][formattedgraph]
- [FormattedGraph]: ../../assets/user_guides/components/formatted_graph.png
+[formattedgraph]: ../../assets/user_guides/components/formatted_graph.png
+[graph]: ../../assets/user_guides/components/graph.png
diff --git a/vizro-core/docs/pages/user-guides/install.md b/vizro-core/docs/pages/user-guides/install.md
index 4d4c01239..6a07911e5 100644
--- a/vizro-core/docs/pages/user-guides/install.md
+++ b/vizro-core/docs/pages/user-guides/install.md
@@ -8,8 +8,8 @@ We recommend that you create a virtual environment for each Vizro project you wo
## Prerequisites to working locally
-* **Python**: Vizro supports macOS, Linux, and Windows. It works with Python 3.9 and later.
-* **Virtual environment**: You specify the version of Python to use with Vizro when you set up the virtual environment. See the following references to learn more about [Python virtual environments](https://realpython.com/python-virtual-environments-a-primer/), [Conda virtual environments](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#starting-conda) or [watch an explainer video about them](https://youtu.be/YKfAwIItO7M).
+- **Python**: Vizro supports macOS, Linux, and Windows. It works with Python 3.9 and later.
+- **Virtual environment**: You specify the version of Python to use with Vizro when you set up the virtual environment. See the following references to learn more about [Python virtual environments](https://realpython.com/python-virtual-environments-a-primer/), [Conda virtual environments](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#starting-conda) or [watch an explainer video about them](https://youtu.be/YKfAwIItO7M).
### How to create a virtual environment for your Vizro project
diff --git a/vizro-core/docs/pages/user-guides/kedro-data-catalog.md b/vizro-core/docs/pages/user-guides/kedro-data-catalog.md
index 0e2b0954e..ce4b060fa 100644
--- a/vizro-core/docs/pages/user-guides/kedro-data-catalog.md
+++ b/vizro-core/docs/pages/user-guides/kedro-data-catalog.md
@@ -3,6 +3,7 @@
This page describes how to integrate Vizro with [Kedro](https://docs.kedro.org/en/stable/index.html), an open-source Python framework to create reproducible, maintainable, and modular data science code. For Pandas datasets registered in a Kedro data catalog, Vizro provides a convenient way to visualize them.
## Installation
+
If you already have Kedro installed then you do not need to install any extra dependencies. If you do not have Kedro installed then you should run:
```bash
@@ -10,7 +11,9 @@ pip install vizro[kedro]
```
## Use datasets from the Kedro Data Catalog
+
`vizro.integrations.kedro` provides functions to help generate and process a [Kedro Data Catalog](https://docs.kedro.org/en/stable/data/index.html). Given a Kedro Data Catalog `catalog`, the general pattern to add datasets into the Vizro data manager is:
+
```python
from vizro.integrations import kedro as kedro_integration
from vizro.managers import data_manager
@@ -25,15 +28,14 @@ This imports all datasets of type [`kedro_datasets.pandas`](https://docs.kedro.o
The `catalog` variable may have been created in a number of different ways:
1. Kedro project path. Vizro exposes a helper function `vizro.integrations.kedro.catalog_from_project` to generate a `catalog` given the path to a Kedro project.
-2. [Kedro Jupyter session](https://docs.kedro.org/en/stable/notebooks_and_ipython/kedro_and_notebooks.html). This automatically exposes `catalog`.
-3. Data Catalog configuration file (`catalog.yaml`). This can create a `catalog` entirely independently of a Kedro project using [`kedro.io.DataCatalog.from_config`](https://docs.kedro.org/en/stable/kedro.io.DataCatalog.html#kedro.io.DataCatalog.from_config).
+1. [Kedro Jupyter session](https://docs.kedro.org/en/stable/notebooks_and_ipython/kedro_and_notebooks.html). This automatically exposes `catalog`.
+1. Data Catalog configuration file (`catalog.yaml`). This can create a `catalog` entirely independently of a Kedro project using [`kedro.io.DataCatalog.from_config`](https://docs.kedro.org/en/stable/kedro.io.DataCatalog.html#kedro.io.DataCatalog.from_config).
The full code for these different cases is given below.
!!! example "Import a Kedro Data Catalog into the Vizro data manager"
-
=== "app.py (Kedro project path)"
- ```py
+ ```python
from vizro.integrations import kedro as kedro_integration
from vizro.managers import data_manager
@@ -43,16 +45,18 @@ The full code for these different cases is given below.
for dataset_name, dataset in kedro_integration.datasets_from_catalog(catalog).items():
data_manager[dataset_name] = dataset
```
+
=== "app.ipynb (Kedro Jupyter session)"
- ```py
+ ```python
from vizro.managers import data_manager
for dataset_name, dataset in kedro_integration.datasets_from_catalog(catalog).items():
data_manager[dataset_name] = dataset
```
+
=== "app.py (Data Catalog configuration file)"
- ```py
+ ```python
from kedro.io import DataCatalog
import yaml
diff --git a/vizro-core/docs/pages/user-guides/layouts.md b/vizro-core/docs/pages/user-guides/layouts.md
index 8361560db..af66ec301 100644
--- a/vizro-core/docs/pages/user-guides/layouts.md
+++ b/vizro-core/docs/pages/user-guides/layouts.md
@@ -3,11 +3,10 @@
The [`Page`][vizro.models.Page] model accepts a `layout` argument that enables custom arrangement of charts and components on the screen. This guide shows how to customize the grid specifications in the [`Layout`][vizro.models.Layout].
## The default layout
-The `layout` argument of the [`Page`][vizro.models.Page] model is optional. If no layout is specified, all charts/components are automatically [**stacked vertically**](layouts.md#vertical-and-horizontal-stacking) on the page in one column.
-If you are happy with that arrangement, you can create your charts/components without providing a [`Layout`][vizro.models.Layout].
-!!! example "Default Layout"
+The `layout` argument of the [`Page`][vizro.models.Page] model is optional. If no layout is specified, all charts/components are automatically [**stacked vertically**](layouts.md#vertical-and-horizontal-stacking) on the page in one column. If you are happy with that arrangement, you can create your charts/components without providing a [`Layout`][vizro.models.Layout].
+!!! example "Default Layout"
=== "app.py"
```{.python pycafe-link}
from vizro import Vizro
@@ -23,35 +22,33 @@ If you are happy with that arrangement, you can create your charts/components wi
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- title: two_left
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ title: two_left
```
- === "Result"
- [![Layout]][Layout]
-
- [Layout]: ../../assets/user_guides/layout/two_left.png
-
+ === "Result"
+ [![Layout]][layout]
## Configure the grid
+
To customize the grid arrangement, configure the `grid` parameter of the [`Layout`][vizro.models.Layout] model.
The example below shows an example of a valid `grid`:
```python title="Basic example"
-grid = [[0, 1],
- [0, 2]]
+grid = [[0, 1], [0, 2]]
```
- The `grid` must be provided as `list[list[int]]` (for example, `grid = [[0, 1], [0, 2]]`).
@@ -64,16 +61,12 @@ grid = [[0, 1],
- The area spanned by a chart/component in the grid must be rectangular.
- The grid can be arbitrarily large, allowing arbitrarily granular control of the grid.
-
## Vertical and horizontal stacking
+
As described above, when no `Layout` is specified, components are presented **vertically** as a single-column stack. If you have three components, the default `Layout.grid` will be as follows, with three equally sized rows, each containing a component spanning the entire width:
```python title="Vertical stacking"
-grid = [
- [0],
- [1],
- [2]
- ]
+grid = [[0], [1], [2]]
```
To present components **horizontally** in one row:
@@ -89,8 +82,8 @@ This defines a single row that occupies the entire width and height, divided int
## Grid - basic example
-!!! example "Grid Arrangement - Basic Example"
+!!! example "Grid Arrangement - Basic Example"
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -109,39 +102,37 @@ This defines a single row that occupies the entire width and height, divided int
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- - text: |
- # Component 2
- type: card
- layout:
- grid: [[0, 1], [0, 2]]
- title: one_left_two_right
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ layout:
+ grid: [[0, 1], [0, 2]]
+ title: one_left_two_right
```
- === "Result"
- [![Grid]][Grid]
- [Grid]: ../../assets/user_guides/layout/one_left_two_right.png
+ === "Result"
+ [![Grid]][grid]
## Grid - advanced example
If you want to divide the grid into subgrids with finer control over these, you can use [`Containers`](container.md). See our section on [when to use `Containers` vs. `Page.layout`](container.md#when-to-use-containers) for more information.
-The `Layout` provides full control over the arrangement of top-level components within a page,
-allowing arbitrarily granular control of the grid by creating larger grids.
+The `Layout` provides full control over the arrangement of top-level components within a page, allowing arbitrarily granular control of the grid by creating larger grids.
!!! example "Grid Arrangement - Advanced Example"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -208,6 +199,7 @@ allowing arbitrarily granular control of the grid by creating larger grids.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -260,44 +252,44 @@ allowing arbitrarily granular control of the grid by creating larger grids.
grid: [[0, 1, 3, 4], [2, 2, 3, 4]]
title: Custom Layout - Advanced Example
```
- === "Result"
- [![GridAdv]][GridAdv]
- [GridAdv]: ../../assets/user_guides/layout/grid_advanced.png
+ === "Result"
+ [![GridAdv]][gridadv]
## Custom layout examples
+
Here is a reference table of example layouts:
+
one row with one component, second row with two components stacked horizontally
-| Layout needed | Grid | Code |
-|--------------------------------|----------------------------|-------------------------------------------------------------------------------------|
-| | | `layout=vm.Layout(grid=[[0]])` |
-| | | `layout=vm.Layout(grid=[[0],[1]])` |
-| | | `layout=vm.Layout(grid=[[0,1]])` |
-| | | `layout=vm.Layout(grid=[[0],[1],[2]])` or
`layout=None` |
-| | | `layout=vm.Layout(grid=[[0,1],[0,2]])` |
-| | | `layout=vm.Layout(grid=[[0,0],[1,2]])` |
-| | | `layout=vm.Layout(grid=[[0,1],[2,2]])` |
-| | | `layout=vm.Layout(grid=[[0,1],[0,2],[0,3]])` |
-| | | `layout=vm.Layout(grid=[[0,1],[2,3]])` |
-| | | `layout=vm.Layout(grid=[[0,3],[1,3],[2,3]])` |
-| | | `layout=vm.Layout(grid=[[0,0,0],[1,2,3]])` |
-| | | `layout=vm.Layout(grid=[[0,1,2],[3,3,3]])` |
+| Layout needed | Grid | Code |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| | | `layout=vm.Layout(grid=[[0]])` |
+| | | `layout=vm.Layout(grid=[[0],[1]])` |
+| | | `layout=vm.Layout(grid=[[0,1]])` |
+| | | `layout=vm.Layout(grid=[[0],[1],[2]])` or
`layout=None` |
+| | | `layout=vm.Layout(grid=[[0,1],[0,2]])` |
+| | | `layout=vm.Layout(grid=[[0,0],[1,2]])` |
+| | | `layout=vm.Layout(grid=[[0,1],[2,2]])` |
+| | | `layout=vm.Layout(grid=[[0,1],[0,2],[0,3]])` |
+| | | `layout=vm.Layout(grid=[[0,1],[2,3]])` |
+| | | `layout=vm.Layout(grid=[[0,3],[1,3],[2,3]])` |
+| | | `layout=vm.Layout(grid=[[0,0,0],[1,2,3]])` |
+| | | `layout=vm.Layout(grid=[[0,1,2],[3,3,3]])` |
## Add empty sections to the grid
+
One approach to organize the dashboard's layout involves integrating empty sections by specifying `-1` within the grid layout.
```python title="Example"
-grid = [[0, 1, -1],
- [0, 2, -1]]
+grid = [[0, 1, -1], [0, 2, -1]]
```
!!! example "Adding Empty Spaces"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -316,38 +308,38 @@ grid = [[0, 1, -1],
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- - text: |
- # Component 2
- type: card
- layout:
- grid: [[0, 1, -1], [0, 2, -1]]
- title: Adding empty spaces
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ layout:
+ grid: [[0, 1, -1], [0, 2, -1]]
+ title: Adding empty spaces
```
- === "Result"
- [![GridEmpty]][GridEmpty]
- [GridEmpty]: ../../assets/user_guides/layout/layout_empty_spaces.png
+ === "Result"
+ [![GridEmpty]][gridempty]
## Control the scroll behavior
+
By default, the grid fits all charts/components on the screen. This can lead to distortions such that the chart/component looks squashed. To control the scroll behavior, you can specify the following:
- `row_min_height`: Sets a chart/component's minimum height. Defaults to 0px.
- `col_min_width`: Sets a chart/component's minimum width. Defaults to 0px.
!!! example "Activate Scrolling"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -371,59 +363,63 @@ By default, the grid fits all charts/components on the screen. This can lead to
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- - text: |
- # Component 2
- type: card
- - text: |
- # Component 2
- type: card
- - text: |
- # Component 4
- type: card
- - text: |
- # Component 5
- type: card
- - text: |
- # Component 6
- type: card
- - text: |
- # Component 7
- type: card
- layout:
- grid: [[0], [1], [2], [3], [4], [5], [6], [7]]
- row_min_height: 240px
- title: Activate scrolling
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ - text: |
+ # Component 4
+ type: card
+ - text: |
+ # Component 5
+ type: card
+ - text: |
+ # Component 6
+ type: card
+ - text: |
+ # Component 7
+ type: card
+ layout:
+ grid: [[0], [1], [2], [3], [4], [5], [6], [7]]
+ row_min_height: 240px
+ title: Activate scrolling
```
- === "Result"
- [![GridScroll]][GridScroll]
-
- [GridScroll]: ../../assets/user_guides/layout/grid_scroll.png
+ === "Result"
+ [![GridScroll]][gridscroll]
## Further customization
-For further customization, such as changing the gap between row and column, refer to the
-documentation of the [`Layout`][vizro.models.Layout] model.
+
+For further customization, such as changing the gap between row and column, refer to the documentation of the [`Layout`][vizro.models.Layout] model.
## Alternative layout approaches
+
In general, any arbitrarily granular layout can already be achieved using [`Page.layout`](layouts.md) alone and is our recommended approach if you want to arrange components on a page with consistent row and/or column spacing.
!!! note "Alternative layout approaches: `Tabs` and `Containers`"
-
- [`Tabs`][vizro.models.Tabs] and [`Containers`][vizro.models.Container] provide an alternative approach to customize your page layout.
- For example, if you want to have more granular control and break the overall page grid into subgrids, see our [user guide on Containers](container.md).
+ [`Tabs`][vizro.models.Tabs] and [`Containers`][vizro.models.Container] offer an alternative approach to customize your page layout. For example, if you want to have more granular control and break the overall page grid into subgrids, see our [user guide on Containers](container.md).
If you want to display multiple containers on one page by putting them into the same screen space, and letting the user switch between them, see our [user guide on Tabs](tabs.md).
{ width="500" }
+
+[grid]: ../../assets/user_guides/layout/one_left_two_right.png
+[gridadv]: ../../assets/user_guides/layout/grid_advanced.png
+[gridempty]: ../../assets/user_guides/layout/layout_empty_spaces.png
+[gridscroll]: ../../assets/user_guides/layout/grid_scroll.png
+[layout]: ../../assets/user_guides/layout/two_left.png
diff --git a/vizro-core/docs/pages/user-guides/navigation.md b/vizro-core/docs/pages/user-guides/navigation.md
index 41c6bb9dc..75a661470 100644
--- a/vizro-core/docs/pages/user-guides/navigation.md
+++ b/vizro-core/docs/pages/user-guides/navigation.md
@@ -2,8 +2,7 @@
This guide shows you how to use and customize the navigation that appears on the left of your dashboard.
-The [`Dashboard`][vizro.models.Dashboard] model accepts a `navigation` argument, where you can enter a [`Navigation`][vizro.models.Navigation] model. This enables you to group pages together and customize how they appear in your navigation.
-The dashboard includes a collapsible side panel that users can minimize or expand by a button click. The collapse button, located in the top right corner of the side panel, is visible by default for user convenience.
+The [`Dashboard`][vizro.models.Dashboard] model accepts a `navigation` argument, where you can enter a [`Navigation`][vizro.models.Navigation] model. This enables you to group pages together and customize how they appear in your navigation. The dashboard includes a collapsible side panel that users can minimize or expand by a button click. The collapse button, located in the top right corner of the side panel, is visible by default for user convenience.
## Use the default navigation
@@ -56,8 +55,8 @@ By default, if the `navigation` argument is not specified, Vizro creates a navig
type: graph
title: My first page
- components:
- - text: My text here
- type: card
+ - text: My text here
+ type: card
title: My second page
- components:
- figure:
@@ -69,10 +68,9 @@ By default, if the `navigation` argument is not specified, Vizro creates a navig
type: graph
title: My third page
```
- === "Result"
- [![DefaultNavigation]][DefaultNavigation]
- [DefaultNavigation]: ../../assets/user_guides/navigation/default_navigation.png
+ === "Result"
+ [![DefaultNavigation]][defaultnavigation]
## Include a subset of pages
@@ -132,17 +130,15 @@ To include only some of your dashboard pages in your navigation then list them i
- My first page
- My second page
```
- === "Result"
- [![OnlySomePages]][OnlySomePages]
- [OnlySomePages]: ../../assets/user_guides/navigation/only_some_pages.png
+ === "Result"
+ [![OnlySomePages]][onlysomepages]
## Group pages
You can also group your pages together by specifying `pages` as a dictionary:
!!! example "Grouping pages"
-
=== "snippet.py"
```py
# page_1, page_2, page_3 defined as in default example
@@ -154,7 +150,6 @@ You can also group your pages together by specifying `pages` as a dictionary:
```
=== "app.py"
-
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -187,6 +182,7 @@ You can also group your pages together by specifying `pages` as a dictionary:
)
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -200,18 +196,15 @@ You can also group your pages together by specifying `pages` as a dictionary:
Group B:
- My third page
```
- === "Result"
- [![GroupedNavigation]][GroupedNavigation]
-
- [GroupedNavigation]: ../../assets/user_guides/navigation/grouped_navigation.png
+ === "Result"
+ [![GroupedNavigation]][groupednavigation]
## Use a navigation bar with icons
Another way to group together pages in the navigation is to use a [`NavBar`][vizro.models.NavBar] with icons. The simplest way to use this is to change the `nav_selector` specified in [`Navigation`][vizro.models.Navigation]:
!!! example "Using `NavBar`"
-
=== "snippet.py"
```py
# page_1, page_2, page_3 defined as in default example
@@ -223,8 +216,8 @@ Another way to group together pages in the navigation is to use a [`NavBar`][viz
)
Vizro().build(dashboard).run()
```
- === "app.py"
+ === "app.py"
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -276,14 +269,11 @@ Another way to group together pages in the navigation is to use a [`NavBar`][viz
nav_selector:
type: nav_bar
```
- === "Result"
- [![NavBar]][NavBar]
-
- [NavBar]: ../../assets/user_guides/navigation/nav_bar.png
+ === "Result"
+ [![NavBar]][navbar]
-Here, the first level of the navigation hierarchy ("Group A" and "Group B") is represented by an icon in a navigation bar, and the second level of the navigation (the pages) is represented by an accordion.
-By default, the set of icons used are the [`filter` icons from the Google Material icons library](https://fonts.google.com/icons?icon.query=filter). The icon label ("Group A" and "Group B") appears as a tooltip on hovering over the icon.
+Here, the first level of the navigation hierarchy ("Group A" and "Group B") is represented by an icon in a navigation bar, and the second level of the navigation (the pages) is represented by an accordion. By default, the set of icons used are the [`filter` icons from the Google Material icons library](https://fonts.google.com/icons?icon.query=filter). The icon label ("Group A" and "Group B") appears as a tooltip on hovering over the icon.
## Customize the navigation bar
@@ -314,7 +304,6 @@ The same configuration for [grouping pages](#group-pages) applies inside a `NavL
```
=== "app.py"
-
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -375,10 +364,9 @@ The same configuration for [grouping pages](#group-pages) applies inside a `NavL
Group B:
- My third page
```
- === "Result"
- [![AccordionInsideNavBar]][AccordionInsideNavBar]
- [AccordionInsideNavBar]: ../../assets/user_guides/navigation/accordion_inside_nav_bar.png
+ === "Result"
+ [![AccordionInsideNavBar]][accordioninsidenavbar]
You can alter the icons used by specifying the name of the icon in the [Google Material icons library](https://fonts.google.com/icons):
@@ -402,8 +390,8 @@ You can alter the icons used by specifying the name of the icon in the [Google M
),
)
```
- === "app.py"
+ === "app.py"
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -468,7 +456,13 @@ You can alter the icons used by specifying the name of the icon in the [Google M
pages:
- My third page
```
- === "Result"
- [![CustomIcons]][CustomIcons]
- [CustomIcons]: ../../assets/user_guides/navigation/custom_icons.png
+ === "Result"
+ [![CustomIcons]][customicons]
+
+[accordioninsidenavbar]: ../../assets/user_guides/navigation/accordion_inside_nav_bar.png
+[customicons]: ../../assets/user_guides/navigation/custom_icons.png
+[defaultnavigation]: ../../assets/user_guides/navigation/default_navigation.png
+[groupednavigation]: ../../assets/user_guides/navigation/grouped_navigation.png
+[navbar]: ../../assets/user_guides/navigation/nav_bar.png
+[onlysomepages]: ../../assets/user_guides/navigation/only_some_pages.png
diff --git a/vizro-core/docs/pages/user-guides/pages.md b/vizro-core/docs/pages/user-guides/pages.md
index 7ae944e9b..71e01e9f9 100644
--- a/vizro-core/docs/pages/user-guides/pages.md
+++ b/vizro-core/docs/pages/user-guides/pages.md
@@ -1,7 +1,6 @@
# How to use pages
-This guide shows you how to add pages to your dashboard and customize the URL paths if needed.
-A [`Page`][vizro.models.Page] lets you place and arrange your dashboard content (for example, chart/components, tables, and text)
-and configure your dashboard interactions (such as filters and parameters).
+
+This guide shows you how to add pages to your dashboard and customize the URL paths if needed. A [`Page`][vizro.models.Page] lets you place and arrange your dashboard content (for example, chart/components, tables, and text) and configure your dashboard interactions (such as filters and parameters).
The [`Dashboard`][vizro.models.Dashboard] model accepts the `pages` argument, where you can insert your [`Page`][vizro.models.Page].
@@ -10,19 +9,19 @@ The [`Dashboard`][vizro.models.Dashboard] model accepts the `pages` argument, wh
A [`Page`][vizro.models.Page] is split up into four main containers:
1. The **navigation container** where you can customize your `navigation` (see [Dashboard](dashboard.md) and [Navigation](navigation.md) for more information). Note that the navigation container needs to be configured via the Dashboard.
-2. The **control container** where you can add your `controls` (see [Filters](filters.md) or [Parameters](parameters.md)) to interact with the dashboard
-3. The **page header** that contains the page title and the theme toggle switch button
-4. The **component container** where you can add your [components](components.md) to visualize your data
+1. The **control container** where you can add your `controls` (see [Filters](filters.md) or [Parameters](parameters.md)) to interact with the dashboard
+1. The **page header** that contains the page title and the theme toggle switch button
+1. The **component container** where you can add your [components](components.md) to visualize your data
To create and add a page to your dashboard, do the following steps:
1. Set a `title` for your [`Page`][vizro.models.Page]
-2. Configure your `components`, see our guide on the [various options](components.md)
-3. (optional) Configure your `controls` , see our guides on [Filters](filters.md) and [Parameters](parameters.md)
-4. (optional) Configure your `layout` , see our guide on [Layouts](layouts.md)
-5. (optional) Give a `description` of your `Page` to the app's [meta tags](https://metatags.io/)
+1. Configure your `components`, see our guide on the [various options](components.md)
+1. (optional) Configure your `controls` , see our guides on [Filters](filters.md) and [Parameters](parameters.md)
+1. (optional) Configure your `layout` , see our guide on [Layouts](layouts.md)
+1. (optional) Give a `description` of your `Page` to the app's [meta tags](https://metatags.io/)
!!! example "Page"
=== "app.py"
@@ -51,51 +50,47 @@ To create and add a page to your dashboard, do the following steps:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: sunburst
- path: ['continent', 'country']
- values: pop
- color: lifeExp
- data_frame: gapminder
- id: sunburst
- type: graph
- controls:
- - column: continent
- targets:
- - sunburst
- type: filter
- - selector:
- options: ['lifeExp', 'pop']
- title: Color
- type: radio_items
- targets:
- - sunburst.color
- type: parameter
- title: Page Title
- description: "Longer description of the page content"
+ - components:
+ - figure:
+ _target_: sunburst
+ path: [continent, country]
+ values: pop
+ color: lifeExp
+ data_frame: gapminder
+ id: sunburst
+ type: graph
+ controls:
+ - column: continent
+ targets: [sunburst]
+ type: filter
+ - selector:
+ options: [lifeExp, pop]
+ title: Color
+ type: radio_items
+ targets: [sunburst.color]
+ type: parameter
+ title: Page Title
+ description: Longer description of the page content
```
- === "Result"
- [![Page]][Page]
- [Page]: ../../assets/user_guides/pages/page_sunburst.png
+ === "Result"
+ [![Page]][page]
An accordion page selector is automatically added to your dashboard in the top-left of the control container for through the different pages. It will not be added if your dashboard consists of only one page.
You can additionally navigate through the different pages by going directly to the relevant page URL (more details in next section).
-
## Customize the page URL
-By default, the page URL is automatically generated based on the `id` of the page. For example, if `id="This is my first page"`
-the generated page URL will be `path=this-is-my-first-page`. You can then access the page via `localhost:/this-is-my-first-page`.
-Note that the page `id` defaults to be the same as the page `title` if not set.
-If you have multiple pages with the same `title` then you must assign a unique `id`.
+By default, the page URL is automatically generated based on the `id` of the page. For example, if `id="This is my first page"` the generated page URL will be `path=this-is-my-first-page`. You can then access the page via `localhost:/this-is-my-first-page`.
+
+Note that the page `id` defaults to be the same as the page `title` if not set. If you have multiple pages with the same `title` then you must assign a unique `id`.
The first page always has the URL prefix `/` assigned. A custom URL can, therefore, not be created for the first page.
@@ -137,39 +132,40 @@ To customize the page URL, pass a valid URL name to the `path` argument of [`Pag
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- Commodi repudiandae consequuntur voluptatum.
- type: card
- title: Page 1
- - components:
- - figure:
- _target_: sunburst
- path: ['continent', 'country']
- values: pop
- color: lifeExp
- data_frame: gapminder
- id: sunburst
- type: graph
- controls:
- - column: continent
- targets:
- - sunburst
- type: filter
- - selector:
- options: ['lifeExp', 'pop']
- title: Color
- type: radio_items
- targets:
- - sunburst.color
- type: parameter
- title: Page 2
- path: my-custom-url
+ - components:
+ - text: |
+ Commodi repudiandae consequuntur voluptatum.
+ type: card
+ title: Page 1
+ - components:
+ - figure:
+ _target_: sunburst
+ path: [continent, country]
+ values: pop
+ color: lifeExp
+ data_frame: gapminder
+ id: sunburst
+ type: graph
+ controls:
+ - column: continent
+ targets: [sunburst]
+ type: filter
+ - selector:
+ options: [lifeExp, pop]
+ title: Color
+ type: radio_items
+ targets: [sunburst.color]
+ type: parameter
+ title: Page 2
+ path: my-custom-url
```
You can now access the first page via `localhost:/` and the second page via `localhost:/my-custom-url`.
+
+[page]: ../../assets/user_guides/pages/page_sunburst.png
diff --git a/vizro-core/docs/pages/user-guides/parameters.md b/vizro-core/docs/pages/user-guides/parameters.md
index bb39a7a0c..c82707d4a 100644
--- a/vizro-core/docs/pages/user-guides/parameters.md
+++ b/vizro-core/docs/pages/user-guides/parameters.md
@@ -9,8 +9,8 @@ The [`Page`][vizro.models.Page] model accepts the `controls` argument, where you
To add a parameter to your page, do the following:
1. add the [`Parameter`][vizro.models.Parameter] model into the `controls` argument of the [`Page`][vizro.models.Page] model.
-2. add the `targets` argument
-3. add a selector model to the `selector` argument.
+1. add the `targets` argument
+1. add a selector model to the `selector` argument.
In the `targets` argument, you can specify the component and function argument that the parameter should be applied to in the form of `.` (for example, `scatter_chart.title`).
@@ -48,6 +48,7 @@ Unlike for the [`Filter`][vizro.models.Filter] model, you also have to configure
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -64,18 +65,17 @@ Unlike for the [`Filter`][vizro.models.Filter] model, you also have to configure
type: graph
controls:
- selector:
- options: ["My scatter chart", "A better title!", "Another title..."]
- multi: False
+ options: [My scatter chart, A better title!, Another title...]
+ multi: false
type: dropdown
targets:
- scatter_chart.title
type: parameter
title: My first page
```
- === "Result"
- [![Parameter]][Parameter]
- [Parameter]: ../../assets/user_guides/control/control4.png
+ === "Result"
+ [![Parameter]][parameter]
If you would like to pass `None` as a parameter and make a parameter optional, you can specify the string `"NONE"` in the `options` or `value` field.
@@ -133,6 +133,7 @@ If you want to change nested parameters, you can specify the `targets` argument
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -146,7 +147,7 @@ If you want to change nested parameters, you can specify the `targets` argument
y: sepal_length
size: petal_length
color: species
- color_discrete_map: {"setosa": "#00b4ff", "versicolor": "#ff9222"}
+ color_discrete_map: {setosa: '#00b4ff', versicolor: '#ff9222'}
id: scatter_chart
type: graph
- figure:
@@ -155,23 +156,22 @@ If you want to change nested parameters, you can specify the `targets` argument
x: sepal_width
y: sepal_length
color: species
- color_discrete_map: {"setosa": "#00b4ff", "versicolor": "#ff9222"}
+ color_discrete_map: {setosa: '#00b4ff', versicolor: '#ff9222'}
id: bar_chart
type: graph
controls:
- selector:
- options: ["#ff5267", "#3949ab"]
+ options: ['#ff5267', '#3949ab']
value: #3949ab
- multi: False
+ multi: false
type: dropdown
- targets: ["scatter_chart.color_discrete_map.virginica", "bar_chart.color_discrete_map.virginica"]
+ targets: [scatter_chart.color_discrete_map.virginica, bar_chart.color_discrete_map.virginica]
type: parameter
title: My first page
```
- === "Result"
- [![Nested]][Nested]
- [Nested]: ../../assets/user_guides/control/control5.png
+ === "Result"
+ [![Nested]][nested]
In the above example, the object passed to the function argument `color_discrete_map` is a dictionary which maps the different flower species to fixed colors (for example, `{"virginica":"blue"}`). In this case, only the value `blue` should be changed instead of the entire dictionary. This can be achieved by specifying a target as `scatter.color_discrete_map.virginica`.
@@ -180,3 +180,6 @@ Note that in the above example, one parameter affects multiple targets.
## Dynamic data parameters
If you use [dynamic data](data.md/#dynamic-data) that can be updated while the dashboard is running then you can pass parameters to the dynamic data function to alter the data loaded into your dashboard. For detailed instructions, refer to the section on [parametrized data loading](data.md/#parametrize-data-loading).
+
+[nested]: ../../assets/user_guides/control/control5.png
+[parameter]: ../../assets/user_guides/control/control4.png
diff --git a/vizro-core/docs/pages/user-guides/run.md b/vizro-core/docs/pages/user-guides/run.md
index df52e8c14..028eb5027 100644
--- a/vizro-core/docs/pages/user-guides/run.md
+++ b/vizro-core/docs/pages/user-guides/run.md
@@ -15,7 +15,6 @@ Most of our examples have a link below the code, [Run and edit this code in PyCa
You can use [PyCafe](https://py.cafe/snippet/vizro/v1) snippet mode to experiment with your own Vizro dashboards by dropping code into a new project.
-
## Default built-in Flask development server
!!! example "Default built-in Flask development server"
@@ -38,9 +37,10 @@ You can use [PyCafe](https://py.cafe/snippet/vizro/v1) snippet mode to experimen
Vizro().build(dashboard).run()
```
+
1. create a Python file named `app.py`.
-2. type the command `python app.py` into your terminal.
-3. information below will be displayed in your terminal, go to [http://127.0.0.1:8050/](http://127.0.0.1:8050/).
+1. type the command `python app.py` into your terminal.
+1. information below will be displayed in your terminal, go to [http://127.0.0.1:8050/](http://127.0.0.1:8050/).
```
Dash is running on http://127.0.0.1:8050/
@@ -51,8 +51,7 @@ INFO:werkzeug:WARNING: This is a development server. Do not use it in a producti
```
!!! warning "In production"
-
- As per the above warning message, which is [further explained in the Flask documentation](https://flask.palletsprojects.com/en/3.0.x/deploying/), the Flask development server is intended for use only during local development and **should not** be used when deploying to production. Instead, you should instead use a production-ready solution such as [Gunicorn](#gunicorn).
+ The above warning message is [further explained in the Flask documentation](https://flask.palletsprojects.com/en/3.0.x/deploying/). The Flask development server is intended for use only during local development and **should not** be used when deploying to production. Instead, you should instead use a production-ready solution such as [Gunicorn](#gunicorn).
### Automatic reloading and debugging
@@ -64,11 +63,11 @@ Setting `debug=True` enables [Dash Dev Tools](https://dash.plotly.com/devtools).
In addition, some errors generated at run time can also be viewed via the browser console (for example in `Chrome` see `View > Developer > Developer Tools > Console`).
-
## Jupyter
+
The dashboard application can be launched in a Jupyter environment in `inline`, `external`, and `jupyterlab` mode.
-!!! example "Run in a Jupyter Notebook in inline mode"
+!!! example "Run in a Jupyter Notebook in inline mode"
=== "app.ipynb"
```py linenums="1"
from vizro import Vizro
@@ -87,16 +86,16 @@ The dashboard application can be launched in a Jupyter environment in `inline`,
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run(jupyter_mode="external")
```
+
- by default, the mode is set to `inline` in `run()` and the dashboard will be displayed inside your Jupyter environment.
- you can specify `jupyter_mode="external"` and a link will be displayed to direct you to the localhost where the dashboard is running.
- you can use tab mode by `jupyter_mode="tab"` to automatically open the app in a new browser
!!! note "Reloading and debugging"
-
Code reloading and hot reloading do not work within a Jupyter Notebook. Instead, there are two methods to reload the dashboard:
- * Restart the Jupyter kernel and re-run your notebook.
- * Add a cell containing `from vizro import Vizro; Vizro._reset()` to the top of your notebook and re-run it. With this method, there is no need to restart the Jupyter kernel.
+ - Restart the Jupyter kernel and re-run your notebook.
+ - Add a cell containing `from vizro import Vizro; Vizro._reset()` to the top of your notebook and re-run it. With this method, there is no need to restart the Jupyter kernel.
## Gunicorn
@@ -126,17 +125,18 @@ The dashboard application can be launched in a Jupyter environment in `inline`,
```
1. The Vizro `app` object is a WSGI application that exposes the underlying Flask app; this will be used by Gunicorn.
- 2. Enable the same app to still be run using the built-in Flask server with `python app.py` for development purposes.
+ 1. Enable the same app to still be run using the built-in Flask server with `python app.py` for development purposes.
To run using Gunicorn with four worker processes, execute
+
```bash
gunicorn app:app --workers 4
```
+
in the command line. For more Gunicorn configuration options, refer to [Gunicorn documentation](https://docs.gunicorn.org/).
!!! warning "In production"
-
- If your dashboard uses [dynamic data](data.md#dynamic-data) that can be refreshed while the dashboard is running then you should [configure your data manager cache](data.md#configure-cache) to use a backend that supports multiple processes.
+ If your dashboard uses [dynamic data](data.md#dynamic-data) that can be refreshed while the dashboard is running then you should [configure your data manager cache](data.md#configure-cache) to use a back end that supports multiple processes.
## Deployment
@@ -149,6 +149,6 @@ Internally, `app = Vizro()` contains a Flask app in `app.dash.server`. However,
[`Vizro`][vizro.Vizro] accepts `**kwargs` that are passed through to `Dash`. This enables you to configure the underlying Dash app using the same [arguments that are available](https://dash.plotly.com/reference#dash.dash) in `Dash`. For example, in a deployment context, these arguments may be useful:
-- `url_base_pathname`: serve your Vizro app at a specific path rather than at the domain root. For example, if you host your dashboard at http://www.example.com/my_dashboard/ then you would set `url_base_pathname="/my_dashboard/"` or an environment variable `DASH_URL_BASE_PATHNAME="/my_dashboard/"`.
+- `url_base_pathname`: serve your Vizro app at a specific path rather than at the domain root. For example, if you host your dashboard at `http://www.example.com/my_dashboard/` then you would set `url_base_pathname="/my_dashboard/"` or an environment variable `DASH_URL_BASE_PATHNAME="/my_dashboard/"`.
- `serve_locally`: set to `False` to [serve Dash component libraries from a Content Delivery Network (CDN)](https://dash.plotly.com/external-resources#serving-dash's-component-libraries-locally-or-from-a-cdn), which reduces load on the server and can improve performance. Vizro uses [jsDeliver](https://www.jsdelivr.com/) as a CDN for CSS and JavaScript sources.
- `assets_external_path`: when `serve_locally=False`, you can also set `assets_external_path` or an environment variable `DASH_ASSETS_EXTERNAL_PATH` to [serve your own assets from a CDN](https://dash.plotly.com/external-resources#load-assets-from-a-folder-hosted-on-a-cdn).
diff --git a/vizro-core/docs/pages/user-guides/selectors.md b/vizro-core/docs/pages/user-guides/selectors.md
index 10481d2ba..a1bd4be20 100644
--- a/vizro-core/docs/pages/user-guides/selectors.md
+++ b/vizro-core/docs/pages/user-guides/selectors.md
@@ -6,10 +6,7 @@ The [`Filter`][vizro.models.Filter] or the [`Parameter`][vizro.models.Parameter]
## Categorical selectors
-Within the categorical selectors, a clear distinction exists between multi-option and single-option selectors.
-For instance, the [`Checklist`][vizro.models.Checklist] functions as a multi-option selector by default while
-the [`RadioItem`][vizro.models.RadioItems] serves as a single-option selector by default. However, the
-[`Dropdown`][vizro.models.Dropdown] can function as both a multi-option or single-option selector.
+Within the categorical selectors, a clear distinction exists between multi-option and single-option selectors. For instance, the [`Checklist`][vizro.models.Checklist] functions as a multi-option selector by default while the [`RadioItem`][vizro.models.RadioItems] serves as a single-option selector by default. However, the [`Dropdown`][vizro.models.Dropdown] can function as both a multi-option or single-option selector.
For more information, refer to the API reference of the selector, or the documentation of its underlying Dash component:
@@ -18,15 +15,12 @@ For more information, refer to the API reference of the selector, or the documen
- [`RadioItems`][vizro.models.RadioItems] based on [`dcc.RadioItems`](https://dash.plotly.com/dash-core-components/radioitems)
!!! note
-
- When configuring the `options` of the categorical selectors, you can either provide:
+ When configuring the `options` of the categorical selectors, you can either give:
- a list of values `options = ['Value A', 'Value B', 'Value C']`
- or a dictionary of label-value mappings `options=[{'label': 'True', 'value': True}, {'label': 'False', 'value': False}]`
- The later is required if you want to provide different display labels to your option values or in case you want to
- provide boolean values as options. In this case, you need to provide a string label for your boolean values as
- boolean values cannot be displayed properly as labels in the underlying Dash components.
+ The later is required if you want to provide different display labels to your option values or in case you want to provide boolean values as options. In this case, you need to provide a string label for your boolean values as boolean values cannot be displayed properly as labels in the underlying Dash components.
## Numerical selectors
@@ -36,11 +30,7 @@ For more information, refer to the API reference of the selector, or the documen
- [`RangeSlider`][vizro.models.RangeSlider] based on [`dcc.RangeSlider`](https://dash.plotly.com/dash-core-components/rangeslider)
!!! note
-
- When configuring the [`Slider`][vizro.models.Slider] and the [`RangeSlider`][vizro.models.RangeSlider] with float values, and using `step` with an integer value, you may notice
- unexpected behavior, such as the drag value being outside its indicated marks.
- To our knowledge, this is a current bug in the underlying [`dcc.Slider`](https://dash.plotly.com/dash-core-components/slider) and
- [`dcc.RangeSlider`](https://dash.plotly.com/dash-core-components/rangeslider) component, which you can circumvent by adapting the `step` size accordingly.
+ When configuring the [`Slider`][vizro.models.Slider] and the [`RangeSlider`][vizro.models.RangeSlider] with float values, and using `step` with an integer value, you may notice unexpected behavior, such as the drag value being outside its indicated marks. To our knowledge, this is a current bug in the underlying [`dcc.Slider`](https://dash.plotly.com/dash-core-components/slider) and [`dcc.RangeSlider`](https://dash.plotly.com/dash-core-components/rangeslider) component, which you can circumvent by adapting the `step` size as needed.
## Temporal selectors
@@ -49,7 +39,6 @@ For more information, refer to the API reference of the selector, or the documen
- [`DatePicker`][vizro.models.DatePicker] based on [`dmc.DateRangePicker`](https://www.dash-mantine-components.com/components/datepicker#daterangepicker) and [`dmc.DatePicker`](https://www.dash-mantine-components.com/components/datepicker)
!!! note
-
When the [`DatePicker`][vizro.models.DatePicker] is configured with `range=True` (the default), the underlying component is `dmc.DateRangePicker`. When `range=False` the underlying component is `dmc.DatePicker`.
When configuring the [`DatePicker`][vizro.models.DatePicker] make sure to provide your dates for `min`, `max` and `value` arguments in `"yyyy-mm-dd"` format or as `datetime` type (for example, `datetime.datetime(2024, 01, 01)`).
diff --git a/vizro-core/docs/pages/user-guides/table.md b/vizro-core/docs/pages/user-guides/table.md
index 19197c465..80e8e53dc 100755
--- a/vizro-core/docs/pages/user-guides/table.md
+++ b/vizro-core/docs/pages/user-guides/table.md
@@ -2,46 +2,32 @@
This guide shows you how to visualize tables in Vizro.
-There are two ways to visualize tables in Vizro, using either [AG Grid](#ag-grid) or [Dash DataTable](#dash-datatable).
-In general, [AG Grid](#ag-grid) is Vizro's recommended table implementation, but sometimes it may make sense to use the [Dash DataTable](#dash-datatable) instead.
+There are two ways to visualize tables in Vizro, using either [AG Grid](#ag-grid) or [Dash DataTable](#dash-datatable). In general, [AG Grid](#ag-grid) is Vizro's recommended table implementation, but sometimes it may make sense to use the [Dash DataTable](#dash-datatable) instead.
## Choose between AG Grid and Dash DataTable
-Vizro offers two models - the [`AgGrid`][vizro.models.AgGrid] model and the [`Table`][vizro.models.Table] model - for the above two approaches respectively.
-They both visualize tabular data in similar ways.
+Vizro offers two models - the [`AgGrid`][vizro.models.AgGrid] model and the [`Table`][vizro.models.Table] model - for the above two approaches respectively. They both visualize tabular data in similar ways.
-The main difference between the two is that the [`AgGrid`][vizro.models.AgGrid] model is based on Plotly's [Dash AG Grid](https://dash.plotly.com/dash-ag-grid) component,
-while the [`Table`][vizro.models.Table] model is based on the [Dash DataTable](https://dash.plotly.com/datatable) component.
-
-Both approaches have similar base features, and are configurable in similar ways. However, the AG Grid offers more advanced features out-of-the-box, is more customizable
-and also ships a powerful enterprise version. This is why it is Vizro's recommended table implementation. At the same time, the Dash DataTable can be used if developers are
-already familiar with it, or if some custom functionality is easier to implement using the Dash DataTable.
+The main difference between the two is that the [`AgGrid`][vizro.models.AgGrid] model is based on Plotly's [Dash AG Grid](https://dash.plotly.com/dash-ag-grid) component, while the [`Table`][vizro.models.Table] model is based on the [Dash DataTable](https://dash.plotly.com/datatable) component.
+Both approaches have similar base features, and are configurable in similar ways. However, the AG Grid offers more advanced features out-of-the-box, is more customizable and also ships a powerful enterprise version. This is why it is Vizro's recommended table implementation. At the same time, the Dash DataTable can be used if developers are already familiar with it, or if some custom functionality is easier to implement using the Dash DataTable.
## AG Grid
-[AG Grid](https://www.ag-grid.com/) is an interactive table/grid component designed for viewing, editing, and exploring large datasets. It
-is Vizro's recommended table implementation.
+[AG Grid](https://www.ag-grid.com/) is an interactive table/grid component designed for viewing, editing, and exploring large datasets. It is Vizro's recommended table implementation.
-The Vizro [`AgGrid`][vizro.models.AgGrid] model is based on the [Dash AG Grid](https://dash.plotly.com/dash-ag-grid), which is in turn based the
-original [Javascript implementation](https://www.ag-grid.com/).
+The Vizro [`AgGrid`][vizro.models.AgGrid] model is based on the [Dash AG Grid](https://dash.plotly.com/dash-ag-grid), which is in turn based the original [Javascript implementation](https://www.ag-grid.com/).
### Basic usage
To add a [`AgGrid`][vizro.models.AgGrid] to your page, do the following:
-1. Insert the [`AgGrid`][vizro.models.AgGrid] model into the `components` argument of the
-[`Page`][vizro.models.Page] model.
-2. Enter the `dash_ag_grid` function under the `figure` argument (imported via `from vizro.tables import dash_ag_grid`).
-
-The Vizro version of this AG Grid differs in one way from the original Dash AG Grid: it requires the user to pass a pandas DataFrame as the source of data.
-As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`. Most other [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments.
-Note that some defaults are set for some arguments (for example, for `columnDefs`) to help with styling and usability.
-Sometimes a parameter may not work because it requires a callback to function. In that case you can try [creating a custom AG Grid callable](custom-tables.md).
+1. Insert the [`AgGrid`][vizro.models.AgGrid] model into the `components` argument of the [`Page`][vizro.models.Page] model.
+1. Enter the `dash_ag_grid` function under the `figure` argument (imported via `from vizro.tables import dash_ag_grid`).
+The Vizro version of this AG Grid differs in one way from the original Dash AG Grid: it requires the user to pass a pandas DataFrame as the source of data. As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`. Most other [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments. Note that some defaults are set for some arguments (for example, for `columnDefs`) to help with styling and usability. Sometimes a parameter may not work because it requires a callback to function. In that case you can try [creating a custom AG Grid callable](custom-tables.md).
!!! example "Basic Dash AG Grid"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -59,29 +45,28 @@ Sometimes a parameter may not work because it requires a callback to function. I
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - figure:
- _target_: dash_ag_grid
- data_frame: gapminder
- type: ag_grid
- title: Default Dash AG Grid
+ - components:
+ - figure:
+ _target_: dash_ag_grid
+ data_frame: gapminder
+ type: ag_grid
+ title: Default Dash AG Grid
```
- === "Result"
- [![AGGrid]][AGGrid]
- [AGGrid]: ../../assets/user_guides/table/aggrid.png
+ === "Result"
+ [![AGGrid]][aggrid]
### Enable pagination
-Pagination is a visual alternative to using vertical scroll. It can also improve loading time if you have many rows.
-You can turn it on by setting `dashGridOptions={"pagination": True}`.
-!!! example "Basic Dash AG Grid"
+Pagination is a visual alternative to using vertical scroll. It can also improve loading time if you have many rows. You can turn it on by setting `dashGridOptions={"pagination": True}`.
+!!! example "Basic Dash AG Grid"
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -99,37 +84,34 @@ You can turn it on by setting `dashGridOptions={"pagination": True}`.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - figure:
- _target_: dash_ag_grid
- data_frame: gapminder
- dashGridOptions:
- pagination: true
- type: ag_grid
- title: Dash AG Grid with pagination
+ - components:
+ - figure:
+ _target_: dash_ag_grid
+ data_frame: gapminder
+ dashGridOptions:
+ pagination: true
+ type: ag_grid
+ title: Dash AG Grid with pagination
```
- === "Result"
- [![AGGrid]][AGGrid]
- [AGGrid]: ../../assets/user_guides/table/aggrid-pagination.png
+ === "Result"
+ [![AGGrid]][aggrid]
### Formatting columns
#### Numbers
-One of the most common tasks when working with tables is to format the columns so that displayed numbers are more readable.
-To do this, you can use the native functionality of [value formatters](https://dash.plotly.com/dash-ag-grid/value-formatters)
-or the Vizro pre-defined [custom cell data types](https://dash.plotly.com/dash-ag-grid/cell-data-types#providing-custom-cell-data-types) as shown below.
+One of the most common tasks when working with tables is to format the columns so that displayed numbers are more readable. To do this, you can use the native functionality of [value formatters](https://dash.plotly.com/dash-ag-grid/value-formatters) or the Vizro pre-defined [custom cell data types](https://dash.plotly.com/dash-ag-grid/cell-data-types#providing-custom-cell-data-types) as shown below.
The available custom cell types for Vizro are `dollar`, `euro`, `percent` and `numeric`.
-To use these, define your desired `` alongside the chosen `cellDataType` in
-the `columnDefs` argument of your `dash_ag_grid` function:
+To use these, define your desired `` alongside the chosen `cellDataType` in the `columnDefs` argument of your `dash_ag_grid` function:
```py
columnDefs = [{"field": "", "cellDataType": "euro"}]
@@ -138,7 +120,6 @@ columnDefs = [{"field": "", "cellDataType": "euro"}]
In the example below we select and format some columns of the gapminder data.
!!! example "AG Grid with formatted columns"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -168,6 +149,7 @@ In the example below we select and format some columns of the gapminder data.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -190,33 +172,23 @@ In the example below we select and format some columns of the gapminder data.
type: ag_grid
title: Example of AG Grid with formatted columns
```
- === "Result"
- [![AGGrid2]][AGGrid2]
- [AGGrid2]: ../../assets/user_guides/table/formatted_aggrid.png
+ === "Result"
+ [![AGGrid2]][aggrid2]
#### Dates
-For the [`AgGrid`][vizro.models.AgGrid] model to sort and filter dates correctly, the date must either be of
-string format `yyyy-mm-dd` (see [Dash AG Grid docs](https://dash.plotly.com/dash-ag-grid/date-filters#example:-date-filter))
-or a pandas datetime object. Any pandas datetime column will be transformed into the `yyyy-mm-dd` format automatically.
+For the [`AgGrid`][vizro.models.AgGrid] model to sort and filter dates correctly, the date must either be of string format `yyyy-mm-dd` (see [Dash AG Grid docs](https://dash.plotly.com/dash-ag-grid/date-filters#example:-date-filter)) or a pandas datetime object. Any pandas datetime column will be transformed into the `yyyy-mm-dd` format automatically.
#### Objects and strings
-No specific formatting is available for custom objects and strings, however you can make use of [Value Formatters](https://dash.plotly.com/dash-ag-grid/value-formatters)
-to format displayed strings automatically.
-
+No specific formatting is available for custom objects and strings, however you can make use of [Value Formatters](https://dash.plotly.com/dash-ag-grid/value-formatters) to format displayed strings automatically.
### Styling and changing the AG Grid
-As mentioned above, all [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments. Below you can find
-an example of a styled AG Grid where some conditional formatting is applied, and where the columns are editable, but
-not filterable or resizable. There are more ways to alter the grid beyond this showcase. AG Grid, like any other Vizro
-component, can be customized using custom CSS. You can find information in
-the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-selected-components).
+As mentioned above, all [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments. Below you can find an example of a styled AG Grid where some conditional formatting is applied, and where the columns are editable, but not filterable or resizable. There are more ways to alter the grid beyond this showcase. AG Grid, like any other Vizro component, can be customized using custom CSS. You can find information in the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-selected-components).
!!! example "Styled and modified Dash AG Grid"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -284,6 +256,7 @@ the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-select
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -299,28 +272,28 @@ the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-select
- field: year
- field: lifeExp
valueFormatter:
- function: "d3.format('.1f')(params.value)"
+ function: d3.format('.1f')(params.value)
- field: gdpPercap
valueFormatter:
- function: "d3.format('$,.1f')(params.value)"
+ function: d3.format('$,.1f')(params.value)
cellStyle:
styleConditions:
- condition: params.value < 1045
style:
- backgroundColor: "#ff9222"
+ backgroundColor: '#ff9222'
- condition: params.value >= 1045 && params.value <= 4095
style:
- backgroundColor: "#de9e75"
+ backgroundColor: '#de9e75'
- condition: params.value > 4095 && params.value <= 12695
style:
- backgroundColor: "#aaa9ba"
+ backgroundColor: '#aaa9ba'
- condition: params.value > 12695
style:
- backgroundColor: "#00b4ff"
+ backgroundColor: '#00b4ff'
- field: pop
type: rightAligned
valueFormatter:
- function: "d3.format(',.0f')(params.value)"
+ function: d3.format(',.0f')(params.value)
defaultColDef:
resizable: false
filter: false
@@ -329,10 +302,9 @@ the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-select
type: ag_grid
title: Example of a Dash AG Grid
```
- === "Result"
- [![AGGrid3]][AGGrid3]
- [AGGrid3]: ../../assets/user_guides/table/styled_aggrid.png
+ === "Result"
+ [![AGGrid3]][aggrid3]
If the available arguments are not sufficient, there is always the option to [create a custom AG Grid callable](custom-tables.md).
@@ -348,19 +320,14 @@ The Vizro [`Table`][vizro.models.Table] model is based on the [Dash DataTable](h
To add a [`Table`][vizro.models.Table] to your page, do the following:
-1. Insert the [`Table`][vizro.models.Table] model into the `components` argument of the
-[`Page`][vizro.models.Page] model.
-2. Enter the `dash_data_table` function under the `figure` argument (imported via `from vizro.tables import dash_data_table`).
-
+1. Insert the [`Table`][vizro.models.Table] model into the `components` argument of the [`Page`][vizro.models.Page] model.
+1. Enter the `dash_data_table` function under the `figure` argument (imported via `from vizro.tables import dash_data_table`).
-The Vizro version of this table differs in one way from the original table: it requires the user to pass a pandas DataFrame as the source of data.
-As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`.
+The Vizro version of this table differs in one way from the original table: it requires the user to pass a pandas DataFrame as the source of data. As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`.
-All other [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Note that we are
-setting some defaults for some arguments to help with styling.
+All other [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Note that we are setting some defaults for some arguments to help with styling.
!!! example "Dash DataTable"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -380,31 +347,29 @@ setting some defaults for some arguments to help with styling.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: dash_data_table
- data_frame: gapminder_2007
- title: Dash DataTable
- type: table
- title: Example of a Dash DataTable
+ - components:
+ - figure:
+ _target_: dash_data_table
+ data_frame: gapminder_2007
+ title: Dash DataTable
+ type: table
+ title: Example of a Dash DataTable
```
- === "Result"
- [![Table]][Table]
- [Table]: ../../assets/user_guides/table/table.png
+ === "Result"
+ [![Table]][table]
### Styling and changing the Dash DataTable
-As mentioned above, all [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Below you can find
-an example of a styled table where some conditional formatting is applied. There are many more ways to alter the table beyond this showcase.
+As mentioned above, all [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Below you can find an example of a styled table where some conditional formatting is applied. There are many more ways to alter the table beyond this showcase.
!!! example "Styled Dash DataTable"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -467,6 +432,7 @@ an example of a styled table where some conditional formatting is applied. There
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -504,12 +470,12 @@ an example of a styled table where some conditional formatting is applied. There
backgroundColor: dodgerblue
color: white
- if:
- filter_query: "{lifeExp} < 55"
+ filter_query: '{lifeExp} < 55'
column_id: lifeExp
- backgroundColor: "#85144b"
+ backgroundColor: '#85144b'
color: white
- if:
- filter_query: "{gdpPercap} > 10000"
+ filter_query: '{gdpPercap} > 10000'
column_id: gdpPercap
backgroundColor: green
color: white
@@ -524,26 +490,20 @@ an example of a styled table where some conditional formatting is applied. There
title: Dash DataTable
```
- === "Result"
- [![Table2]][Table2]
- [Table2]: ../../assets/user_guides/table/styled_table.png
+ === "Result"
+ [![Table2]][table2]
If the available arguments are not sufficient, there is always the option to create a [custom Dash DataTable](custom-tables.md).
-
## Add title, header, and footer
-The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] models accept a `title`, `header` and
-`footer` argument. This is useful for providing context to the data being displayed, or for adding a description of
-the data.
+The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] models accept a `title`, `header` and `footer` argument. This is useful for providing context to the data being displayed, or for adding a description of the data.
- **title**: Displayed as an [H3 header](https://dash.plotly.com/dash-html-components/h3), useful for summarizing the main topic or insight of the component.
- **header**: Accepts markdown text, ideal for extra descriptions, subtitles, or detailed data insights.
- **footer**: Accepts markdown text, commonly used for citing data sources, providing information on the last update, or adding disclaimers.
-
-
### Formatted AgGrid
!!! example "Formatted AgGrid"
@@ -571,30 +531,29 @@ the data.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: dash_ag_grid
- data_frame: gapminder_2007
- dashGridOptions:
- pagination: true
- title: Gapminder Data Insights
- header: |
- #### An Interactive Exploration of Global Health, Wealth, and Population
- footer: |
- SOURCE: **Plotly gapminder data set, 2024**
- type: ag_grid
- title: Formatted AgGrid
+ - components:
+ - figure:
+ _target_: dash_ag_grid
+ data_frame: gapminder_2007
+ dashGridOptions:
+ pagination: true
+ title: Gapminder Data Insights
+ header: |
+ #### An Interactive Exploration of Global Health, Wealth, and Population
+ footer: |
+ SOURCE: **Plotly gapminder data set, 2024**
+ type: ag_grid
+ title: Formatted AgGrid
```
- === "Result"
- [![FormattedGrid]][FormattedGrid]
-
- [FormattedGrid]: ../../assets/user_guides/components/formatted_aggrid.png
+ === "Result"
+ [![FormattedGrid]][formattedgrid]
### Formatted DataTable
@@ -623,24 +582,32 @@ the data.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: dash_data_table
- data_frame: gapminder_2007
- title: Gapminder Data Insights
- header: |
- #### An Interactive Exploration of Global Health, Wealth, and Population
- footer: |
- SOURCE: **Plotly gapminder data set, 2024**
- type: table
- title: Formatted DataTable
+ - components:
+ - figure:
+ _target_: dash_data_table
+ data_frame: gapminder_2007
+ title: Gapminder Data Insights
+ header: |
+ #### An Interactive Exploration of Global Health, Wealth, and Population
+ footer: |
+ SOURCE: **Plotly gapminder data set, 2024**
+ type: table
+ title: Formatted DataTable
```
- === "Result"
- [![FormattedTable]][FormattedTable]
- [FormattedTable]: ../../assets/user_guides/components/formatted_table.png
+ === "Result"
+ [![FormattedTable]][formattedtable]
+
+[aggrid]: ../../assets/user_guides/table/aggrid.png
+[aggrid2]: ../../assets/user_guides/table/formatted_aggrid.png
+[aggrid3]: ../../assets/user_guides/table/styled_aggrid.png
+[formattedgrid]: ../../assets/user_guides/components/formatted_aggrid.png
+[formattedtable]: ../../assets/user_guides/components/formatted_table.png
+[table]: ../../assets/user_guides/table/table.png
+[table2]: ../../assets/user_guides/table/styled_table.png
diff --git a/vizro-core/docs/pages/user-guides/tabs.md b/vizro-core/docs/pages/user-guides/tabs.md
index 09154177e..1811d0cac 100755
--- a/vizro-core/docs/pages/user-guides/tabs.md
+++ b/vizro-core/docs/pages/user-guides/tabs.md
@@ -1,8 +1,6 @@
# How to use tabs
-[`Tabs`][vizro.models.Tabs] organize and separate groups of related content in a dashboard, letting users switch between different sections or views.
-They are essentially a way of putting multiple [`Containers`][vizro.models.Container] in the same screen space, and letting the user switch between them.
-`Containers` enable the grouping of page components into sections and subsections. See our [user guide on `Containers`](container.md) for more information.
+[`Tabs`][vizro.models.Tabs] organize and separate groups of related content in a dashboard, letting users switch between different sections or views. They are essentially a way of putting multiple [`Containers`][vizro.models.Container] in the same screen space, and letting the user switch between them. `Containers` enable the grouping of page components into sections and subsections. See our [user guide on `Containers`](container.md) for more information.
{ width="400"}
@@ -16,14 +14,12 @@ This guide shows you how to use tabs to organize your `Containers` into subsecti
By using [`Tabs`][vizro.models.Tabs], the following applies:
- [`Filters`][vizro.models.Filter] affect all components on all tabs (opened and closed) of the page if not specified otherwise inside `Filter.targets`
-- The `title` of the [`Container`][vizro.models.Container] inserted into `Tabs.tabs` will be displayed as a tab label, and the title will be removed from the `Container`
-
+- The `title` of the [`Container`][vizro.models.Container] inserted into `Tabs.tabs` will be displayed as a tab label, and the title will be removed from the `Container`
To add [`Tabs`][vizro.models.Tabs] to your page, do the following:
1. Insert the [`Tabs`][vizro.models.Tabs] into the `components` argument of the [`Page`][vizro.models.Page]
-2. Insert your [`Containers`][vizro.models.Container] into the `tabs` argument of the [`Tabs`][vizro.models.Tabs]
-
+1. Insert your [`Containers`][vizro.models.Container] into the `tabs` argument of the [`Tabs`][vizro.models.Tabs]
!!! example "Tabs"
=== "app.py"
@@ -88,52 +84,53 @@ To add [`Tabs`][vizro.models.Tabs] to your page, do the following:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - tabs:
- - title: Tab I
- type: container
- components:
- - type: graph
- figure:
- _target_: bar
- data_frame: gapminder_2007
- title: Graph 1
- x: continent
- y: lifeExp
- color: continent
- - type: graph
- figure:
- _target_: box
- data_frame: gapminder_2007
- title: Graph 2
- x: continent
- y: lifeExp
- color: continent
- - title: Tab II
- type: container
- components:
- - type: graph
- figure:
- _target_: scatter
- data_frame: gapminder_2007
- title: Graph 3
- x: gdpPercap
- y: lifeExp
- size: pop
- color: continent
- type: tabs
+ components:
+ - type: tabs
+ tabs:
+ - title: Tab I
+ type: container
+ components:
+ - type: graph
+ figure:
+ _target_: bar
+ data_frame: gapminder_2007
+ title: Graph 1
+ x: continent
+ y: lifeExp
+ color: continent
+ - type: graph
+ figure:
+ _target_: box
+ data_frame: gapminder_2007
+ title: Graph 2
+ x: continent
+ y: lifeExp
+ color: continent
+ - title: Tab II
+ type: container
+ components:
+ - type: graph
+ figure:
+ _target_: scatter
+ data_frame: gapminder_2007
+ title: Graph 3
+ x: gdpPercap
+ y: lifeExp
+ size: pop
+ color: continent
controls:
- - type: filter
- column: continent
+ - type: filter
+ column: continent
title: Tabs
```
- === "Result"
- [![Tabs]][Tabs]
+ === "Result"
+ [![Tabs]][tabs]
- [Tabs]: ../../assets/user_guides/components/tabs.png
+[tabs]: ../../assets/user_guides/components/tabs.png
diff --git a/vizro-core/docs/pages/user-guides/themes.md b/vizro-core/docs/pages/user-guides/themes.md
index 6f78441d5..ac1d6fc7b 100644
--- a/vizro-core/docs/pages/user-guides/themes.md
+++ b/vizro-core/docs/pages/user-guides/themes.md
@@ -1,15 +1,13 @@
# How to use themes
-This guide shows you how to use themes. Themes are pre-designed collections of stylings that are applied to entire charts and dashboards.
-The themes provided by Vizro are infused with our design best practices that make charts and dashboards look visually consistent and professional.
+This guide shows you how to use themes. Themes are pre-designed collections of stylings that are applied to entire charts and dashboards. The themes provided by Vizro are infused with our design best practices that make charts and dashboards look visually consistent and professional.
## Themes in dashboards
-The [`Dashboard`][vizro.models.Dashboard] model accepts an optional `theme` argument, where you can choose between
-a `vizro_dark` and a `vizro_light` theme. If not specified then `theme` defaults to `vizro_dark`. The theme is applied to the entire dashboard and its charts/components when a user first loads your dashboard. Regardless of the theme applied on first load, users can always switch between light and dark themes via the toggle button in the upper-right corner of the dashboard.
+
+The [`Dashboard`][vizro.models.Dashboard] model accepts an optional `theme` argument, where you can choose between a `vizro_dark` and a `vizro_light` theme. If not specified then `theme` defaults to `vizro_dark`. The theme is applied to the entire dashboard and its charts/components when a user first loads your dashboard. Regardless of the theme applied on first load, users can always switch between light and dark themes via the toggle button in the upper-right corner of the dashboard.
!!! example "Change theme"
=== "app.py"
-
```{.python pycafe-link hl_lines="18"}
import vizro.models as vm
import vizro.plotly.express as px
@@ -32,47 +30,40 @@ a `vizro_dark` and a `vizro_light` theme. If not specified then `theme` defaults
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml hl_lines="12"
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: scatter_matrix
- color: species
- data_frame: iris
- dimensions: ["sepal_length", "sepal_width", "petal_length", "petal_width"]
- type: graph
- title: Changing themes
+ - components:
+ - figure:
+ _target_: scatter_matrix
+ color: species
+ data_frame: iris
+ dimensions: [sepal_length, sepal_width, petal_length, petal_width]
+ type: graph
+ title: Changing themes
theme: vizro_light
```
+
=== "Result - vizro_light"
- [![Light]][Light]
+ [![Light]][light]
- [Light]: ../../assets/user_guides/themes/light.png
=== "Result - vizro_dark"
- [![Dark]][Dark]
-
- [Dark]: ../../assets/user_guides/themes/dark.png
-
+ [![Dark]][dark]
## Themes in plotly charts
You can also use our templates for plotly charts outside the dashboard. This is useful in a few contexts:
-* Creation of standalone charts to be used independently of a Vizro dashboard.
-* Rapid development of charts for eventual use in a Vizro dashboard, for example in a Jupyter Notebook.
+- Creation of standalone charts to be used independently of a Vizro dashboard.
+- Rapid development of charts for eventual use in a Vizro dashboard, for example in a Jupyter Notebook.
!!! note
+ Using `import vizro.plotly.express as px` is equal to using `import plotly.express as px`, but with the added benefit of being able to integrate the resulting chart code into a Vizro dashboard. Vizro offers a minimal layer on top of Plotly's existing charting library, allowing you to seamlessly use all the existing charts and functionalities provided by plotly.express without any modifications.
- Using `import vizro.plotly.express as px` is equivalent to using `import plotly.express as px`,
- but with the added benefit of being able to integrate the resulting chart code into a Vizro dashboard.
- Vizro offers a minimal layer on top of Plotly's existing charting library, allowing you to seamlessly use all the
- existing charts and functionalities provided by plotly.express without any modifications.
-
-Our `vizro_dark` and `vizro_light` themes are automatically registered to `plotly.io.templates` when importing Vizro.
-Consult the plotly documentation for [more details on how templates work in plotly](https://plotly.com/python/templates/#theming-and-templates).
+Our `vizro_dark` and `vizro_light` themes are automatically registered to `plotly.io.templates` when importing Vizro. Consult the plotly documentation for [more details on how templates work in plotly](https://plotly.com/python/templates/#theming-and-templates).
By default, plots imported from `vizro.plotly.express` have the `vizro_dark` theme applied. This can be altered either globally or for individual plots.
@@ -87,14 +78,20 @@ pio.templates.default = "vizro_light"
```
### Set themes for selected charts
+
To change the template for a selected chart only, use the `template` parameter and run:
```python
import vizro.plotly.express as px
df = px.data.iris()
-px.scatter_matrix(df,
- dimensions=["sepal_length", "sepal_width", "petal_length", "petal_width"],
- color="species",
- template="vizro_light")
+px.scatter_matrix(
+ df,
+ dimensions=["sepal_length", "sepal_width", "petal_length", "petal_width"],
+ color="species",
+ template="vizro_light",
+)
```
+
+[dark]: ../../assets/user_guides/themes/dark.png
+[light]: ../../assets/user_guides/themes/light.png
diff --git a/vizro-core/docs/pages/user-guides/visual-formatting.md b/vizro-core/docs/pages/user-guides/visual-formatting.md
index 7b384f3e9..56d1d2d52 100644
--- a/vizro-core/docs/pages/user-guides/visual-formatting.md
+++ b/vizro-core/docs/pages/user-guides/visual-formatting.md
@@ -1,17 +1,13 @@
# How to customize the style of Vizro dashboards
-Vizro has a default styling to help users with no design experience get started.
-There are several options if you want to customize the style:
+Vizro has a default styling to help users with no design experience get started. There are several options if you want to customize the style:
-* **[Configure the `Layout`](layouts.md)**: Customize the arrangement of your components inside your Vizro dashboard.
+- **[Configure the `Layout`](layouts.md)**: Customize the arrangement of your components inside your Vizro dashboard.
-* **[Apply a theme](themes.md)**: Choose between a dark or light theme.
+- **[Apply a theme](themes.md)**: Choose between a dark or light theme.
-* **[Manage assets](assets.md)**: Enhance your dashboard by adding images, scripts, and stylesheets to your assets folder.
+- **[Manage assets](assets.md)**: Enhance your dashboard by adding images, scripts, and stylesheets to your assets folder.
-* **[Customize CSS](custom-css.md)**: Incorporate custom CSS to deviate from the default styling and create a
-unique appearance for your Vizro dashboard.
+- **[Customize CSS](custom-css.md)**: Incorporate custom CSS to deviate from the default styling and create a unique appearance for your Vizro dashboard.
-* **[Customize your `component`](components.md)**: Change the appearance of components like the [Graph](graph.md), the
-[Table](table.md) and the [AgGrid](table.md), by passing extra arguments. Refer to the relevant user guide for
-more details.
+- **[Customize your `component`](components.md)**: Change the appearance of components like the [Graph](graph.md), the [Table](table.md) and the [AgGrid](table.md), by passing extra arguments. Refer to the relevant user guide for more details.
diff --git a/vizro-core/examples/README.md b/vizro-core/examples/README.md
index 72146bfb7..53cf932b7 100644
--- a/vizro-core/examples/README.md
+++ b/vizro-core/examples/README.md
@@ -4,8 +4,7 @@ Please note that this folder contains only example dashboards that are still **i
### Vizro examples gallery
-To view a comprehensive list of available demos, please visit our [examples gallery](http://vizro.mckinsey.com/).
-There, you can explore a wide range of dashboards and applications created with Vizro.
+To view a comprehensive list of available demos, please visit our [examples gallery](http://vizro.mckinsey.com/). There, you can explore a wide range of dashboards and applications created with Vizro.
diff --git a/vizro-core/examples/visual-vocabulary/README.md b/vizro-core/examples/visual-vocabulary/README.md
index 3b298520e..e59b3103c 100644
--- a/vizro-core/examples/visual-vocabulary/README.md
+++ b/vizro-core/examples/visual-vocabulary/README.md
@@ -2,14 +2,11 @@
### Welcome to our visual vocabulary dashboard! 🎨
-This dashboard serves as a comprehensive guide for selecting and creating various types of charts. It helps you decide
-when to use each chart type, and offers sample Python code using [Plotly](https://plotly.com/python/), and
-instructions for embedding these charts into a [Vizro](https://github.com/mckinsey/vizro) dashboard.
+This dashboard serves as a comprehensive guide for selecting and creating various types of charts. It helps you decide when to use each chart type, and offers sample Python code using [Plotly](https://plotly.com/python/), and instructions for embedding these charts into a [Vizro](https://github.com/mckinsey/vizro) dashboard.
The charts in this dashboard are designed to make it easy for anyone to create beautiful and sophisticated visuals.
-Our goal is to help you understand best practices in data visualization, ensure your charts effectively communicate
-your message, and streamline the creation of high-quality, interactive visualizations.
+Our goal is to help you understand best practices in data visualization, ensure your charts effectively communicate your message, and streamline the creation of high-quality, interactive visualizations.
Created by:
@@ -19,12 +16,9 @@ Created by:
Inspired by:
-- [The FT Visual Vocabulary](https://github.com/Financial-Times/chart-doctor/blob/main/visual-vocabulary/README.md):
- [Alan Smith](https://github.com/alansmithy), [Chris Campbell](https://github.com/digitalcampbell), Ian Bott,
- Liz Faunce, Graham Parrish, Billy Ehrenberg, Paul McCallum, [Martin Stabe](https://github.com/martinstabe).
+- [The FT Visual Vocabulary](https://github.com/Financial-Times/chart-doctor/blob/main/visual-vocabulary/README.md): [Alan Smith](https://github.com/alansmithy), [Chris Campbell](https://github.com/digitalcampbell), Ian Bott, Liz Faunce, Graham Parrish, Billy Ehrenberg, Paul McCallum, [Martin Stabe](https://github.com/martinstabe).
-- [The Graphic Continuum](https://www.informationisbeautifulawards.com/showcase/611-the-graphic-continuum):
- Jon Swabish and Severino Ribecca
+- [The Graphic Continuum](https://www.informationisbeautifulawards.com/showcase/611-the-graphic-continuum): Jon Swabish and Severino Ribecca
Credits and sources:
@@ -102,13 +96,12 @@ The dashboard is still in development. Below is an overview of the chart types f
Contributions are welcome! To contribute a chart, follow the steps below:
1. Check that a `svg` file named after the chart type is contained in the [assets](https://github.com/mckinsey/vizro/tree/main/vizro-core/examples/visual-vocabulary/assets/images/charts) folder. If not, [raise an issue](https://github.com/mckinsey/vizro/issues) in the repository.
-2. Add a `.py` file containing a code example of the chart type in the `pages/examples` folder, for instance, `area.py`. Take a look at existing examples.
-3. Create a new page for the chart type and add it to the relevant category `.py` file such as `correlation.py`,
- `deviation.py`, `distribution.py`, etc. Ensure you add the page to the list of `pages` at the end of the `.py` file.
-4. Remove the `IncompletePage(..)` entry for that chart type in `chart_groups.py`.
-5. Update this `README.md` with the new chart type, its status, category, and API links.
+1. Add a `.py` file containing a code example of the chart type in the `pages/examples` folder, for instance, `area.py`. Take a look at existing examples.
+1. Create a new page for the chart type and add it to the relevant category `.py` file such as `correlation.py`, `deviation.py`, `distribution.py`, etc. Ensure you add the page to the list of `pages` at the end of the `.py` file.
+1. Remove the `IncompletePage(..)` entry for that chart type in `chart_groups.py`.
+1. Update this `README.md` with the new chart type, its status, category, and API links.
## How to run the example locally
1. Run the example with the command `hatch run example visual-vocabulary`.
-2. You should now be able to access the app locally via http://127.0.0.1:8051/.
+1. You should now be able to access the app locally via http://127.0.0.1:8051/.
tag
+ ## This is an tag
- ###### This is an tag
- type: card
- title: Changing the header color
+ ###### This is an tag
+ type: card
+ title: Changing the header color
```
- === "Result"
- [![AssetsCSS]][AssetsCSS]
-
- [AssetsCSS]: ../../assets/user_guides/assets/css_change.png
+ === "Result"
+ [![AssetsCSS]][assetscss]
### Overwrite CSS for selected pages
-To style components for a specific page, use the page's `id` in the CSS selectors. By default, this is the
-[same as the page `title`](pages.md), but such a value might not be a valid CSS identifier.
-A suitable `id` must be unique across all models in the dashboard and should contain only alphanumeric
-characters, hyphens (`-`) and underscores (`_`). In particular, note that spaces are _not_ allowed.
+To style components for a specific page, use the page's `id` in the CSS selectors. By default, this is the [same as the page `title`](pages.md), but such a value might not be a valid CSS identifier.
+
+A suitable `id` must be unique across all models in the dashboard and should contain only alphanumeric characters, hyphens (`-`) and underscores (`_`). In particular, note that spaces are _not_ allowed.
Suppose you want to hide the page title on one page only. Here's how you can achieve this:
1. Give a valid `id` to the `Page`, for example `Page(id="page-with-hidden-title", title="Page with hidden title", ...)`.
-2. Identify the CSS class or CSS `id` you need to target. To hide the page title, you need to hide the parent container with the id `right-header`.
-3. Use the `id` to hide the content.
-4. Add your custom css file to the `assets` folder.
-
+1. Identify the CSS class or CSS `id` you need to target. To hide the page title, you need to hide the parent container with the id `right-header`.
+1. Use the `id` to hide the content.
+1. Add your custom css file to the `assets` folder.
!!! example "Hide page title on selected pages"
=== "my_css_file.css"
- ```css
- #page-with-hidden-title #right-header {
- display: none;
- }
- ```
+ ```css
+ #page-with-hidden-title #right-header {
+ display: none;
+ }
+ ```
+
=== "app.py"
```py
import vizro.models as vm
@@ -199,25 +185,24 @@ Suppose you want to hide the page title on one page only. Here's how you can ach
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Placeholder
- type: card
- title: Page with hidden title
- id: page-with-hidden-title
- - components:
- - text: |
- # Placeholder
- type: card
- title: Page with shown title
+ - components:
+ - text: |
+ # Placeholder
+ type: card
+ title: Page with hidden title
+ id: page-with-hidden-title
+ - components:
+ - text: |
+ # Placeholder
+ type: card
+ title: Page with shown title
```
- === "Result"
- [![PageTitle]][PageTitle]
-
- [PageTitle]: ../../assets/user_guides/assets/css_page_title.png
+ === "Result"
+ [![PageTitle]][pagetitle]
### Overwrite CSS for selected components
+
To adjust CSS properties for specific components, such as altering the appearance of a selected [`Card`][vizro.models.Card] rather than all Cards, you need to supply an `id` to the component you want to style.
Let's say we want to change the `background-color` and `color` of a specific `Card`.
@@ -225,41 +210,43 @@ Let's say we want to change the `background-color` and `color` of a specific `Ca
Here's how you can do it:
1. Assign a unique `id` to the relevant `Card`, for example: `Card(id="custom-card", ...)`
-2. Run your dashboard and open it in your browser
-3. View the HTML document to find the appropriate CSS class or element you need to target, as explained in the section
-on [identifying the correct CSS selector](#identify-the-correct-css-selector).
+1. Run your dashboard and open it in your browser
+1. View the HTML document to find the appropriate CSS class or element you need to target, as explained in the section on [identifying the correct CSS selector](#identify-the-correct-css-selector).
-It's essential to understand the relationship between the targeted CSS class or element and the component assigned
-`id`, for example:
+It's essential to understand the relationship between the targeted CSS class or element and the component assigned `id`, for example:
-```html title="HTML structure of a `Card`"
+
+```html title="HTML structure of a card"
-
- Lorem ipsum dolor sit amet consectetur adipisicing elit.
-
+
+
+ Lorem ipsum dolor sit amet consectetur adipisicing elit.
+
+
```
-
-* **Main element with `id`:** There is a `` with our `id="custom-card"`.
-* **Parent element:** That `` is wrapped inside a parent `` with the class name `"card"`. This is the element we need to target to change the background color.
-* **Child element:** The card text is wrapped inside a `` that is a child of the `
` with our `id`. This is the element we need to target to change the font color.
+
+- **Main element with `id`:** There is a `` with our `id="custom-card"`.
+- **Parent element:** That `` is wrapped inside a parent `` with the class name `"card"`. This is the element we need to target to change the background color.
+- **Child element:** The card text is wrapped inside a `` that is a child of the `
` with our `id`. This is the element we need to target to change the font color.
!!! example "Customizing CSS properties in selective components"
=== "my_css_file.css"
- ```css
- /* Apply styling to parent */
- .card:has(#custom-card) {
- background-color: white;
- }
+ ```css
+ /* Apply styling to parent */
+ .card:has(#custom-card) {
+ background-color: white;
+ }
+
+ /* Apply styling to child */
+ #custom-card p {
+ color: black;
+ }
+ ```
- /* Apply styling to child */
- #custom-card p {
- color: black;
- }
- ```
=== "app.py"
```py
import vizro.models as vm
@@ -285,77 +272,65 @@ It's essential to understand the relationship between the targeted CSS class or
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- Lorem ipsum dolor sit amet consectetur adipisicing elit.
- type: card
- id: custom-card
- - text: |
- Lorem ipsum dolor sit amet consectetur adipisicing elit.
- type: card
- title: Changing the card color
+ - components:
+ - text: |
+ Lorem ipsum dolor sit amet consectetur adipisicing elit.
+ type: card
+ id: custom-card
+ - text: |
+ Lorem ipsum dolor sit amet consectetur adipisicing elit.
+ type: card
+ title: Changing the card color
```
- === "Result"
- [![CardCSS]][CardCSS]
-
- [CardCSS]: ../../assets/user_guides/assets/css_change_card.png
+ === "Result"
+ [![CardCSS]][cardcss]
!!! note "Relationship between model ID and CSS ID"
+ Some Vizro components produce a single HTML element with an ID that matches the model ID, allowing you to target it directly using the CSS #id selector. Other components generate multiple HTML elements. Within these, the "core" element will have an ID matching the model ID, while non-core elements may have IDs that are variations of it, such as `{model-id}-title`.
- Some Vizro components produce a single HTML element with an ID that matches the model ID, allowing you to target it
- directly using the CSS #id selector. Other components generate multiple HTML elements. Within these, the "core"
- element will have an ID matching the model ID, while non-core elements may have IDs that are variations of it,
- such as `{model-id}-title`.
-
- In all instances, you can determine the correct selector by using Chrome DevTools or a similar tool after setting the
- appropriate model ID.
-
+ In all instances, you can determine the correct selector by using Chrome DevTools or a similar tool after setting the appropriate model ID.
## Common examples
### Make your CSS responsive to theme switches with variables
-To ensure your CSS adapts to theme changes, we recommend using CSS variables (`var`) whenever possible. For a
-comprehensive list of available variable names, refer to the
-[Bootstrap documentation](https://getbootstrap.com/docs/5.3/customize/css-variables/). Note that our
-Bootstrap stylesheet is still under development, so not all Bootstrap variables are currently available.
-Additionally, you can define your own CSS variables, as demonstrated in the example on
-[changing the container background color](#change-the-styling-of-a-container).
+
+To ensure your CSS adapts to theme changes, we recommend using CSS variables (`var`) whenever possible. For a comprehensive list of available variable names, refer to the [Bootstrap documentation](https://getbootstrap.com/docs/5.3/customize/css-variables/). Note that our Bootstrap stylesheet is still under development, so not all Bootstrap variables are currently available. Additionally, you can define your own CSS variables, as demonstrated in the example on [changing the container background color](#change-the-styling-of-a-container).
### Turn off page title
+
See the example above on [hiding the page title on selected pages](#overwrite-css-for-selected-pages).
### Change the background color of a card
+
See the example above on [customizing CSS properties in selective components](#overwrite-css-for-selected-components).
### Change the global font
+
The default fonts for a Vizro app are `Inter, sans-serif, Arial, serif`.
If you need to change the global font, perhaps to adhere to branding guidelines, follow these steps:
1. Download the desired font from a font provider such as [Google Fonts](https://fonts.google.com/).
-2. Place the font file (`.ttf`, `woff2`, etc.) into your `assets` folder. Here’s an example of what the assets folder might look like:
- 
+1. Place the font file (`.ttf`, `woff2`, etc.) into your `assets` folder. Here’s an example of what the assets folder might look like:
-3. Add the font to your CSS file using the `@font-face` rule and apply the font globally to your Vizro app, making sure
-to specify fallback fonts. Add the following to your `custom.css` file:
+ 
+1. Add the font to your CSS file using the `@font-face` rule and apply the font globally to your Vizro app, making sure to specify fallback fonts. Add the following to your `custom.css` file:
```css
@font-face {
- font-family: PlayfairDisplay;
- src: url("PlayfairDisplay-VariableFont_wght.ttf") format("truetype");
+ font-family: PlayfairDisplay;
+ src: url("PlayfairDisplay-VariableFont_wght.ttf") format("truetype");
}
* {
- font-family: PlayfairDisplay, Inter, sans-serif, Arial, serif;
+ font-family: PlayfairDisplay, Inter, sans-serif, Arial, serif;
}
```
-
-4. Note that the modification above applies solely to the dashboard font. To also change the font within the
-Plotly charts, you must specify this at the beginning of your `app.py` file:
+1. Note that the modification above applies solely to the dashboard font. To also change the font within the Plotly charts, you must specify this at the beginning of your `app.py` file:
```python
import plotly.io as pio
@@ -365,44 +340,42 @@ Plotly charts, you must specify this at the beginning of your `app.py` file:
```
### Reposition the logo
-By default, the logo appears in the top left corner of the dashboard. You can move it further to the left or right by
-adjusting the `padding` of the `#page-header` element. Here is an example of how to achieve this:
+
+By default, the logo appears in the top left corner of the dashboard. You can move it further to the left or right by adjusting the `padding` of the `#page-header` element. Here is an example of how to achieve this:
```css
#page-header {
- padding-left: 8px;
+ padding-left: 8px;
}
```
-
### Change the styling of a container
-If you want to make the subsections of your dashboard stand out more, you can do this by placing your components
-inside a [Container](container.md) and changing the container's styling, for example, background color, borders, padding, etc.
-To do this, you need to change the container's CSS class. Using the DevTool, as explained in the section on
-[identifying the correct CSS selector](#identify-the-correct-css-selector), you'll find that the CSS class for the
-`Container` is `page-component-container`. You can then use this class to set a new `background-color` and `padding`.
+If you want to make the subsections of your dashboard stand out more, you can do this by placing your components inside a [Container](container.md) and changing the container's styling, for example, background color, borders, padding, etc.
+
+To do this, you need to change the container's CSS class. Using the DevTool, as explained in the section on [identifying the correct CSS selector](#identify-the-correct-css-selector), you'll find that the CSS class for the `Container` is `page-component-container`. You can then use this class to set a new `background-color` and `padding`.
!!! example "Style a container"
=== "custom.css"
- ```css
- /* Assign a variable to the dark and light theme */
- [data-bs-theme="dark"] {
- --container-bg-color: #232632;
- }
-
- [data-bs-theme="light"] {
- --container-bg-color: #F5F6F6;
- }
+ ```css
+ /* Assign a variable to the dark and light theme */
+ [data-bs-theme="dark"] {
+ --container-bg-color: #232632;
+ }
+
+ [data-bs-theme="light"] {
+ --container-bg-color: #F5F6F6;
+ }
+
+ /* Use the custom variable var(--container-bg-color) */
+ .page-component-container {
+ background: var(--container-bg-color);
+ padding: 12px;
+ }
+ ```
- /* Use the custom variable var(--container-bg-color) */
- .page-component-container {
- background: var(--container-bg-color);
- padding: 12px;
- }
- ```
=== "app.py"
```py
import vizro.models as vm
@@ -437,12 +410,12 @@ To do this, you need to change the container's CSS class. Using the DevTool, as
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - title: "Page with subsections"
+ - title: Page with subsections
layout:
grid: [[0, 1]]
components:
- type: container
- title: "Container I"
+ title: Container I
components:
- type: graph
figure:
@@ -452,7 +425,7 @@ To do this, you need to change the container's CSS class. Using the DevTool, as
y: sepal_length
color: species
- type: container
- title: "Container II"
+ title: Container II
components:
- type: graph
figure:
@@ -462,13 +435,11 @@ To do this, you need to change the container's CSS class. Using the DevTool, as
y: sepal_length
color: species
```
- === "Result"
- [![StyleContainer]][StyleContainer]
- [StyleContainer]: ../../assets/user_guides/custom_css/style-container.png
+ === "Result"
+ [![StyleContainer]][stylecontainer]
-You will notice that the background colors of the charts are different. To align it with the colors of the container,
-you can make the charts' background transparent.
+You will notice that the background colors of the charts are different. To align it with the colors of the container, you can make the charts' background transparent.
To make the background of all charts transparent:
@@ -492,3 +463,8 @@ def custom_chart(data_frame):
```
+
+[assetscss]: ../../assets/user_guides/assets/css_change.png
+[cardcss]: ../../assets/user_guides/assets/css_change_card.png
+[pagetitle]: ../../assets/user_guides/assets/css_page_title.png
+[stylecontainer]: ../../assets/user_guides/custom_css/style-container.png
diff --git a/vizro-core/docs/pages/user-guides/custom-figures.md b/vizro-core/docs/pages/user-guides/custom-figures.md
index f135127be..3a178932f 100644
--- a/vizro-core/docs/pages/user-guides/custom-figures.md
+++ b/vizro-core/docs/pages/user-guides/custom-figures.md
@@ -1,41 +1,36 @@
# How to create custom figures
-This guide explains how to create custom figures, which is useful when you need a component that reacts to
-[filter](filters.md) and [parameter](parameters.md) controls.
+This guide explains how to create custom figures, which is 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).
## When to use a custom figure
-As described in the flowchart detailing [when to use `Figure`](figure.md), custom figures should be used if
-**both** of the following conditions are met:
+
+As described in the flowchart detailing [when to use `Figure`](figure.md), custom figures should be used if **both** of the following conditions are met:
- You need a figure that doesn't fit into the existing pre-defined components ([`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid]).
- You need a figure that isn't available in our pre-defined figure functions [`vizro.figures`](../API-reference/figure-callables.md).
## Steps to create a custom figure
-1. Define a function that returns a [Dash component](https://dash.plotly.com/#open-source-component-libraries).
-This can, but does not need to, be based on code in our pre-defined figure functions in [`vizro.figures`](../API-reference/figure-callables.md).
-2. Decorate it with `@capture("figure")`.
-3. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
-4. The figure should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments
-will not react to dashboard controls such as [`Filter`](filters.md).
-5. Pass your function to the `figure` argument of the [`Figure`][vizro.models.Figure] model.
+1. Define a function that returns a [Dash component](https://dash.plotly.com/#open-source-component-libraries). This can, but does not need to, be based on code in our pre-defined figure functions in [`vizro.figures`](../API-reference/figure-callables.md).
+1. Decorate it with `@capture("figure")`.
+1. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
+1. The figure should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments will not react to dashboard controls such as [`Filter`](filters.md).
+1. Pass your function to the `figure` argument of the [`Figure`][vizro.models.Figure] model.
The following examples can be used as a base to build more sophisticated figures.
## Examples of custom figures
### Custom KPI card
-To change the design or content of our existing KPI (key performance indicator) cards from
-[`vizro.figures`](../API-reference/figure-callables.md), you can do so by following the steps described above.
-For instance, to make a KPI card with the icon positioned on the right side of the title instead of the left,
-copy and paste the [source code of `kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card) and
-adjust the return statement of the function.
+To change the design or content of our existing KPI (key performance indicator) cards from [`vizro.figures`](../API-reference/figure-callables.md), you can do so by following the steps described above.
+
+For instance, to make a KPI card with the icon positioned on the right side of the title instead of the left, copy and paste the [source code of `kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card) and adjust the return statement of the function.
+
!!! example "Custom KPI card"
=== "app.py"
```{.python pycafe-link}
@@ -107,29 +102,26 @@ adjust the return statement of the function.
```
1. Here we decorate our custom figure function with the `@capture("figure")` decorator.
- 2. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
- 3. We adjust the return statement to include the icon on the right side of the title. This is achieved by swapping the order of the `html.H2` and `html.P` compared to the original `kpi_card`.
- 4. This creates a [`layout`](layouts.md) with four rows and columns. The KPI cards are positioned in the first two cells, while the remaining cells are empty.
- 5. For more information, refer to the API reference for the [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card).
- 6. Our custom figure function `custom_kpi_card` now needs to be passed on to the `vm.Figure`.
+ 1. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
+ 1. We adjust the return statement to include the icon on the right side of the title. This is achieved by swapping the order of the `html.H2` and `html.P` compared to the original `kpi_card`.
+ 1. This creates a [`layout`](layouts.md) with four rows and columns. The KPI cards are positioned in the first two cells, while the remaining cells are empty.
+ 1. For more information, refer to the API reference for the [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card).
+ 1. Our custom figure function `custom_kpi_card` now needs to be passed on to the `vm.Figure`.
=== "app.yaml"
- ```yaml
- # Custom figures are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomKPI]][CustomKPI]
+ Custom figures are currently only possible via Python configuration.
- [CustomKPI]: ../../assets/user_guides/figure/custom_kpi.png
+ === "Result"
+ [![CustomKPI]][customkpi]
### Dynamic HTML header
-You can create a custom figure for any [Dash component](https://dash.plotly.com/#open-source-component-libraries).
-Below is an example of a custom figure that returns a `html.H2` component that dynamically updates based on the selected
-name from a filter.
+
+You can create a custom figure for any [Dash component](https://dash.plotly.com/#open-source-component-libraries). Below is an example of a custom figure that returns a `html.H2` component that dynamically updates based on the selected name from a filter.
+
!!! example "Dynamic HTML header"
=== "app.py"
```{.python pycafe-link}
@@ -159,27 +151,24 @@ name from a filter.
```
1. Here we decorate our custom figure function with the `@capture("figure")` decorator.
- 2. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
- 3. We return a `html.H2` component that dynamically updates based on the selected name from the filter.
- 4. Our custom figure function `dynamic_html_header` now needs to be passed on to the `vm.Figure`.
+ 1. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
+ 1. We return a `html.H2` component that dynamically updates based on the selected name from the filter.
+ 1. Our custom figure function `dynamic_html_header` now needs to be passed on to the `vm.Figure`.
=== "app.yaml"
- ```yaml
- # Custom figures are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomHTML]][CustomHTML]
+ Custom figures are currently only possible via Python configuration.
- [CustomHTML]: ../../assets/user_guides/figure/custom_html.png
+ === "Result"
+ [![CustomHTML]][customhtml]
-
### Dynamic number of cards
-The example below shows how to create multiple cards created from a `pandas.DataFrame` where the
-number of cards displayed dynamically adjusts based on a `vm.Parameter`.
+
+The example below shows how to create multiple cards created from a `pandas.DataFrame` where the number of cards displayed dynamically adjusts based on a `vm.Parameter`.
+
!!! example "Dynamic number of cards"
=== "app.py"
```py
@@ -239,40 +228,39 @@ number of cards displayed dynamically adjusts based on a `vm.Parameter`.
```
1. Here we decorate our custom figure function with the `@capture("figure")` decorator.
- 2. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
- 3. Our decorated figure function `multiple_cards` now needs to be passed on to the `vm.Figure`.
- 4. We add a [`vm.Parameter`](parameters.md) to dynamically adjust the number of cards displayed.
- The parameter targets the `n_rows` argument of the `multiple_cards` function, determining the number of rows
- taken from the data.
+ 1. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
+ 1. Our decorated figure function `multiple_cards` now needs to be passed on to the `vm.Figure`.
+ 1. We add a [`vm.Parameter`](parameters.md) to dynamically adjust the number of cards displayed. The parameter targets the `n_rows` argument of the `multiple_cards` function, determining the number of rows taken from the data.
Run and edit this code in PyCafe
=== "styling.css"
```css
.multiple-cards-container {
- display: flex;
- flex-wrap: wrap;
- gap: 12px;
+ display: flex;
+ flex-wrap: wrap;
+ gap: 12px;
}
.figure-container {
- height: unset;
- width: unset;
+ height: unset;
+ width: unset;
}
.figure-container .card {
- height: 210px;
- width: 240px;
+ height: 210px;
+ width: 240px;
}
```
- === "app.yaml"
- ```yaml
- # Custom figures are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomFigure]][CustomFigure]
- [CustomFigure]: ../../assets/user_guides/figure/custom_multiple_cards.png
+ === "app.yaml"
+ Custom figures are currently only possible via Python configuration.
+ === "Result"
+ [![CustomFigure]][customfigure]
+
+[customfigure]: ../../assets/user_guides/figure/custom_multiple_cards.png
+[customhtml]: ../../assets/user_guides/figure/custom_html.png
+[customkpi]: ../../assets/user_guides/figure/custom_kpi.png
diff --git a/vizro-core/docs/pages/user-guides/custom-tables.md b/vizro-core/docs/pages/user-guides/custom-tables.md
index e990cfbb0..42748820b 100644
--- a/vizro-core/docs/pages/user-guides/custom-tables.md
+++ b/vizro-core/docs/pages/user-guides/custom-tables.md
@@ -1,21 +1,18 @@
# How to create custom Dash AG Grids and Dash DataTables
-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.
+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.
-The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] model accept the `figure` argument, where you can enter
-_any_ [`dash_ag_grid`][vizro.tables.dash_ag_grid] or [`dash_data_table`][vizro.tables.dash_data_table] chart as explained in the [user guide on tables](table.md).
+The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] model accept the `figure` argument, where you can enter _any_ [`dash_ag_grid`][vizro.tables.dash_ag_grid] or [`dash_data_table`][vizro.tables.dash_data_table] chart as explained in the [user guide on tables](table.md).
One reason could be that you want to create a table/grid that requires computations that can be controlled by parameters (see the example below).
### Steps to create a custom table
1. Define a function that returns a `dash_ag_grid.AgGrid` or `dash_table.DataTable` object.
-2. Decorate it with `@capture("ag_grid")` or `@capture("table")`.
-3. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
-4. The table should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments
-will not react to dashboard controls such as [`Filter`](filters.md).
-5. Pass your function to the `figure` argument of the [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid] model.
+1. Decorate it with `@capture("ag_grid")` or `@capture("table")`.
+1. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
+1. The table should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments will not react to dashboard controls such as [`Filter`](filters.md).
+1. Pass your function to the `figure` argument of the [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid] model.
The following examples show a possible version of a custom table. In this case the argument `chosen_columns` was added, which you can control with a parameter:
@@ -70,14 +67,12 @@ The following examples show a possible version of a custom table. In this case t
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
- ```yaml
- # Custom tables are currently only possible via Python configuration
- ```
- === "Result"
- [![Table3]][Table3]
+ Custom tables are currently only possible via Python configuration.
- [Table3]: ../../assets/user_guides/table/custom_table.png
+ === "Result"
+ [![Table3]][table3]
??? example "Custom Dash AgGrid"
=== "app.py"
@@ -136,11 +131,12 @@ The following examples show a possible version of a custom table. In this case t
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
- ```yaml
- # Custom Ag Grids are currently only possible via Python configuration
- ```
+ Custom Ag Grids are currently only possible via Python configuration.
+
=== "Result"
- [![GridCustom]][GridCustom]
+ [![GridCustom]][gridcustom]
- [GridCustom]: ../../assets/user_guides/table/custom_grid.png
+[gridcustom]: ../../assets/user_guides/table/custom_grid.png
+[table3]: ../../assets/user_guides/table/custom_table.png
diff --git a/vizro-core/docs/pages/user-guides/dashboard.md b/vizro-core/docs/pages/user-guides/dashboard.md
index 0b37e03fa..244f65256 100644
--- a/vizro-core/docs/pages/user-guides/dashboard.md
+++ b/vizro-core/docs/pages/user-guides/dashboard.md
@@ -1,16 +1,15 @@
# How to create a dashboard
-This guide shows you how to configure and call a [`Dashboard`][vizro.models.Dashboard] using either
-pydantic models, Python dictionaries, YAML, or JSON.
+
+This guide shows you how to configure and call a [`Dashboard`][vizro.models.Dashboard] using either pydantic models, Python dictionaries, YAML, or JSON.
To create a dashboard:
1. Choose one of the possible configuration syntaxes
-2. Create your `pages`, see our [guide on Pages](pages.md)
-3. (optional) Choose a `theme`, see our [guide on Themes](themes.md)
-4. (optional) Customize your `navigation`, see our [guide on Navigation](navigation.md)
-5. (optional) Set a `title` for your dashboard
-6. Add your `dashboard` to the `build` call of Vizro
-
+1. Create your `pages`, see our [guide on Pages](pages.md)
+1. (optional) Choose a `theme`, see our [guide on Themes](themes.md)
+1. (optional) Customize your `navigation`, see our [guide on Navigation](navigation.md)
+1. (optional) Set a `title` for your dashboard
+1. Add your `dashboard` to the `build` call of Vizro
## Use dashboard configuration options
@@ -37,6 +36,7 @@ To create a dashboard:
Vizro().build(dashboard).run()
```
+
=== "app.py - Python dict"
```py
import vizro.plotly.express as px
@@ -77,6 +77,7 @@ To create a dashboard:
Vizro().build(dashboard).run()
```
+
=== "dashboard.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -101,50 +102,49 @@ To create a dashboard:
type: filter
title: My first dashboard
```
+
=== "dashboard.json"
```json
{
- "pages": [
+ "pages": [
+ {
+ "components": [
+ {
+ "figure": {
+ "_target_": "scatter",
+ "color": "species",
+ "data_frame": "iris",
+ "x": "sepal_length",
+ "y": "petal_width"
+ },
+ "type": "graph"
+ },
{
- "components": [
- {
- "figure": {
- "_target_": "scatter",
- "color": "species",
- "data_frame": "iris",
- "x": "sepal_length",
- "y": "petal_width"
- },
- "type": "graph"
- },
- {
- "figure": {
- "_target_": "histogram",
- "color": "species",
- "data_frame": "iris",
- "x": "sepal_width",
- },
- "type": "graph"
- }
- ],
- "controls": [
- {
- "column": "species",
- "type": "filter"
- }
- ],
- "title": "My first dashboard"
+ "figure": {
+ "_target_": "histogram",
+ "color": "species",
+ "data_frame": "iris",
+ "x": "sepal_width"
+ },
+ "type": "graph"
}
- ]
+ ],
+ "controls": [
+ {
+ "column": "species",
+ "type": "filter"
+ }
+ ],
+ "title": "My first dashboard"
+ }
+ ]
}
```
- === "Result"
- [![Dashboard]][Dashboard]
- [Dashboard]: ../../assets/user_guides/dashboard/dashboard.png
+ === "Result"
+ [![Dashboard]][dashboard]
!!! note "Extra `.py` files for `yaml` and `json` required"
-
Note that in the `yaml` and `json` example an extra `.py` is required to register the data and parse the yaml/json configuration.
=== "app.py for yaml"
@@ -164,6 +164,7 @@ To create a dashboard:
Vizro().build(dashboard).run()
```
+
=== "app.py for json"
```py
import json
@@ -187,7 +188,6 @@ After running the dashboard, you can access the dashboard via `localhost:8050`.
If supplied, the `title` of the [`Dashboard`][vizro.models.Dashboard] displays a heading at the top of every page.
-
## Add a dashboard logo
Vizro will [automatically incorporate the dashboard logo](assets.md/#add-a-logo-image) in the top-left corner of each page if an image named `logo.` is present within the assets folder.
@@ -196,11 +196,10 @@ Vizro will [automatically incorporate the dashboard logo](assets.md/#add-a-logo-
## Browser title
-The [website icon](assets.md/#change-the-favicon), Dashboard `title` (if supplied) and [Page `title`][vizro.models.Page] are displayed in the browser's
-title bar. For example, if your Dashboard `title` is "Vizro Demo" and the Page `title` is "Homepage", then the title in the browser tab will be "Vizro Demo: Homepage".
+The [website icon](assets.md/#change-the-favicon), Dashboard `title` (if supplied) and [Page `title`][vizro.models.Page] are displayed in the browser's title bar. For example, if your Dashboard `title` is "Vizro Demo" and the Page `title` is "Homepage", then the title in the browser tab will be "Vizro Demo: Homepage".
## Meta tags for social media
-Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat
-clients. The preview includes the `URL`, `title`, plus an [image](assets.md/#include-a-meta-tags-image) and
-[Page `description`][vizro.models.Page] (if supplied). To see an example, try sharing an example from the [Vizro examples gallery](https://vizro.mckinsey.com/).
+Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat clients. The preview includes the `URL`, `title`, plus an [image](assets.md/#include-a-meta-tags-image) and [Page `description`][vizro.models.Page] (if supplied). To see an example, try sharing an example from the [Vizro examples gallery](https://vizro.mckinsey.com/).
+
+[dashboard]: ../../assets/user_guides/dashboard/dashboard.png
diff --git a/vizro-core/docs/pages/user-guides/data.md b/vizro-core/docs/pages/user-guides/data.md
index 51bf84b97..d19b8aafb 100644
--- a/vizro-core/docs/pages/user-guides/data.md
+++ b/vizro-core/docs/pages/user-guides/data.md
@@ -2,11 +2,12 @@
Vizro supports two different types of data:
-* [Static data](#static-data): pandas DataFrame. This is the simplest method and best to use if you do not need the more advanced functionality of dynamic data.
-* [Dynamic data](#dynamic-data): function that returns a pandas DataFrame. This is a bit more complex to understand but has more advanced functionality such as the ability to refresh data while the dashboard is running.
+- [Static data](#static-data): pandas DataFrame. This is the simplest method and best to use if you do not need the more advanced functionality of dynamic data.
+- [Dynamic data](#dynamic-data): function that returns a pandas DataFrame. This is a bit more complex to understand but has more advanced functionality such as the ability to refresh data while the dashboard is running.
The following flowchart shows what you need to consider when choosing how to set up your data.
-``` mermaid
+
+```mermaid
graph TD
refresh["`Do you need your data to refresh while the dashboard is running?`"]
specification["`Do you need to specify your dashboard through a configuration language like YAML?`"]
@@ -27,11 +28,10 @@ graph TD
```
??? note "Static vs. dynamic data comparison"
-
This table gives a full comparison between static and dynamic data. Do not worry if you do not yet understand everything in it; it will become clearer after reading more about [static data](#static-data) and [dynamic data](#dynamic-data)!
| | Static | Dynamic |
- |---------------------------------------------------------------|------------------|------------------------------------------|
+ | ------------------------------------------------------------- | ---------------- | ---------------------------------------- |
| Required Python type | pandas DataFrame | Function that returns a pandas DataFrame |
| Can be supplied directly in `data_frame` argument of `figure` | Yes | No |
| Can be referenced by name after adding to data manager | Yes | Yes |
@@ -73,14 +73,13 @@ The below example uses the Iris data saved to a file `iris.csv` in the same dire
```
1. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
- === "Result"
- [![DataBasic]][DataBasic]
- [DataBasic]: ../../assets/user_guides/data/data_pandas_dataframe.png
+ === "Result"
+ [![DataBasic]][databasic]
The [`Graph`][vizro.models.Graph], [`AgGrid`][vizro.models.AgGrid] and [`Table`][vizro.models.Table] models all have an argument called `figure`. This accepts a function (in the above example, `px.scatter`) that takes a pandas DataFrame as its first argument. The name of this argument is always `data_frame`. When configuring the dashboard using Python, it is optional to give the name of the argument: if you like, you could write `data_frame=iris` instead of `iris`.
-!!! note
+!!! note
With static data, once the dashboard is running, the data shown in the dashboard cannot change even if the source data in `iris.csv` changes. The code `iris = pd.read_csv("iris.csv")` is only executed once when the dashboard is first started. If you would like changes to source data to flow through to the dashboard then you must use [dynamic data](#dynamic-data).
### Reference by name
@@ -107,27 +106,27 @@ If you would like to specify your dashboard configuration through YAML then you
```
1. `"iris"` is the name of a data source added to the data manager. This data is a pandas DataFrame created by reading from the CSV file `iris.csv`.
+
=== "dashboard.yaml"
```yaml
pages:
- - components:
- - figure:
+ - components:
+ figure:
_target_: box
data_frame: iris # (1)!
x: species
y: petal_width
color: species
type: graph
- title: Static data example
+ title: Static data example
```
1. Refer to the `"iris"` data source in the data manager.
- === "Result"
- [![DataBasic]][DataBasic]
- [DataBasic]: ../../assets/user_guides/data/data_pandas_dataframe.png
+ === "Result"
+ [![DataBasic]][databasic]
-It is also possible to refer to a named data source using the Python API: `px.scatter("iris", ...)` or `px.scatter(data_frame="iris", ...)` would work if the `"iris"` data source has been registered in the data manager.
+It is also possible to refer to a named data source using the Python API: `px.scatter("iris", ...)` or `px.scatter(data_frame="iris", ...)` would work if the `"iris"` data source has been registered in the data manager.
## Dynamic data
@@ -166,14 +165,12 @@ The example below shows how data is fetched dynamically every time the page is r
```
1. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
- 2. To demonstrate that dynamic data can change when the page is refreshed, select 50 points at random. This simulates what would happen if your file `iris.csv` were constantly changing.
- 3. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()`; doing so would result in static data that cannot be reloaded.
- 4. Dynamic data is referenced by the name of the data source `"iris"`.
+ 1. To demonstrate that dynamic data can change when the page is refreshed, select 50 points at random. This simulates what would happen if your file `iris.csv` were constantly changing.
+ 1. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()`; doing so would result in static data that cannot be reloaded.
+ 1. Dynamic data is referenced by the name of the data source `"iris"`.
=== "Result"
- [![DynamicData]][DynamicData]
-
- [DynamicData]: ../../assets/user_guides/data/dynamic_data.gif
+ [![DynamicData]][dynamicdata]
Since dynamic data sources must always be added to the data manager and referenced by name, they may be used in YAML configuration [exactly the same way as for static data sources](#reference-by-name).
@@ -184,10 +181,10 @@ By default, a dynamic data function executes every time the dashboard is refresh
The Vizro data manager has a server-side caching mechanism to help solve this. Vizro's cache uses [Flask-Caching](https://flask-caching.readthedocs.io/en/latest/), which supports a number of possible cache backends and [configuration options](https://flask-caching.readthedocs.io/en/latest/#configuring-flask-caching). By default, the cache is turned off.
+
In a development environment the easiest way to enable caching is to use a [simple memory cache](https://cachelib.readthedocs.io/en/stable/simple/) with the default configuration options. This is achieved by adding one line to the above example to set `data_manager.cache`:
!!! example "Simple cache with default timeout of 5 minutes"
-
```py hl_lines="13"
from flask_caching import Cache
from vizro import Vizro
@@ -225,7 +222,6 @@ data_manager.cache = Cache(config={"CACHE_TYPE": "SimpleCache", "CACHE_DEFAULT_T
```
!!! warning
-
Simple cache exists purely for single-process development purposes and is not intended to be used in production. If you deploy with multiple workers, [for example with Gunicorn](run.md/#gunicorn), then you should use a production-ready cache backend. All of Flask-Caching's [built-in backends](https://flask-caching.readthedocs.io/en/latest/#built-in-cache-backends) other than `SimpleCache` are suitable for production. In particular, you might like to use [`FileSystemCache`](https://cachelib.readthedocs.io/en/stable/file/) or [`RedisCache`](https://cachelib.readthedocs.io/en/stable/redis/):
```py title="Production-ready caches"
@@ -239,7 +235,9 @@ data_manager.cache = Cache(config={"CACHE_TYPE": "SimpleCache", "CACHE_DEFAULT_T
Since Flask-Caching relies on [`pickle`](https://docs.python.org/3/library/pickle.html), which can execute arbitrary code during unpickling, you should not cache data from untrusted sources. Doing so [could be unsafe](https://github.com/pallets-eco/flask-caching/pull/209).
Note that when a production-ready cache backend is used, the cache is persisted beyond the Vizro process and is not cleared by restarting your server. To clear the cache then you must do so manually, for example, if you use `FileSystemCache` then you would delete your `cache` directory. Persisting the cache can also be useful for development purposes when handling data that takes a long time to load: even if you do not need the data to refresh while your dashboard is running, it can speed up your development loop to use dynamic data with a cache that is persisted between repeated runs of Vizro.
+
+
#### Set timeouts
You can change the timeout of the cache independently for each dynamic data source in the data manager using the `timeout` setting (measured in seconds). A `timeout` of 0 indicates that the cache does not expire. This is effectively the same as using [static data](#static-data).
@@ -278,8 +276,8 @@ In general, a parametrized dynamic data source should always return a pandas Dat
To add a parameter to control a dynamic data source, do the following:
1. add the appropriate argument to your dynamic data function and specify a default value for the argument.
-2. give an `id` to all components that have the data source you wish to alter through a parameter.
-3. [add a parameter](parameters.md) with `targets` of the form `.data_frame.` and a suitable [selector](selectors.md).
+1. give an `id` to all components that have the data source you wish to alter through a parameter.
+1. [add a parameter](parameters.md) with `targets` of the form `.data_frame.` and a suitable [selector](selectors.md).
For example, let us extend the [dynamic data example](#dynamic-data) above into an example of how parametrized dynamic data works. The `load_iris_data` can take an argument `number_of_points` controlled from the dashboard with a [`Slider`][vizro.models.Slider].
@@ -318,21 +316,18 @@ For example, let us extend the [dynamic data example](#dynamic-data) above into
```
1. `load_iris_data` takes a single argument, `number_of_points`, with a default value of 10.
- 2. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
- 3. Sample points at random, where `number_of_points` gives the number of points selected.
- 4. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()` or `load_iris_data(number_of_points=...)`; doing so would result in static data that cannot be reloaded.
- 5. Give the `vm.Graph` component `id="graph"` so that the `vm.Parameter` can target it. Dynamic data is referenced by the name of the data source `"iris"`.
- 6. Create a `vm.Parameter` to target the `number_of_points` argument for the `data_frame` used in `graph`.
+ 1. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
+ 1. Sample points at random, where `number_of_points` gives the number of points selected.
+ 1. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()` or `load_iris_data(number_of_points=...)`; doing so would result in static data that cannot be reloaded.
+ 1. Give the `vm.Graph` component `id="graph"` so that the `vm.Parameter` can target it. Dynamic data is referenced by the name of the data source `"iris"`.
+ 1. Create a `vm.Parameter` to target the `number_of_points` argument for the `data_frame` used in `graph`.
=== "Result"
- [![ParametrizedDynamicData]][ParametrizedDynamicData]
-
- [ParametrizedDynamicData]: ../../assets/user_guides/data/parametrized_dynamic_data.gif
+ [![ParametrizedDynamicData]][parametrizeddynamicdata]
Parametrized data loading is compatible with [caching](#configure-cache). The cache uses [memoization](https://flask-caching.readthedocs.io/en/latest/#memoization), so that the dynamic data function's arguments are included in the cache key. This means that `load_iris_data(number_of_points=10)` is cached independently of `load_iris_data(number_of_points=20)`.
!!! warning
-
You should always [treat the content of user input as untrusted](https://community.plotly.com/t/writing-secure-dash-apps-community-thread/54619). For example, you should not expose a filepath to load without passing it through a function like [`werkzeug.utils.secure_filename`](https://werkzeug.palletsprojects.com/en/3.0.x/utils/#werkzeug.utils.secure_filename), or you might enable arbitrary access to files on your server.
You cannot pass [nested parameters](parameters.md#nested-parameters) to dynamic data. You can only target the top-level arguments of the data loading function, not the nested keys in a dictionary.
@@ -354,7 +349,6 @@ When the page is refreshed, the behavior of a dynamic filter is as follows:
For example, let us add two filters to the [dynamic data example](#dynamic-data) above:
!!! example "Dynamic filters"
-
```py hl_lines="10 20 21"
from vizro import Vizro
import pandas as pd
@@ -386,8 +380,8 @@ For example, let us add two filters to the [dynamic data example](#dynamic-data)
```
1. We sample only 5 rather than 50 points so that changes to the available values in the filtered columns are more apparent when the page is refreshed.
- 2. This filter implicitly controls the dynamic data source `"iris"`, which supplies the `data_frame` to the targeted `vm.Graph`. On page refresh, Vizro reloads this data, finds all the unique values in the `"species"` column and sets the categorical selector's `options` accordingly.
- 3. Similarly, on page refresh, Vizro finds the minimum and maximum values of the `"sepal_length"` column in the reloaded data and sets new `min` and `max` values for the numerical selector accordingly.
+ 1. This filter implicitly controls the dynamic data source `"iris"`, which supplies the `data_frame` to the targeted `vm.Graph`. On page refresh, Vizro reloads this data, finds all the unique values in the `"species"` column and sets the categorical selector's `options` accordingly.
+ 1. Similarly, on page refresh, Vizro finds the minimum and maximum values of the `"sepal_length"` column in the reloaded data and sets new `min` and `max` values for the numerical selector accordingly.
Consider a filter that depends on dynamic data, where you do **not** want the available values to change when the dynamic data changes. You should manually specify the `selector`'s `options` field (categorical selector) or `min` and `max` fields (numerical selector). In the above example, this could be achieved as follows:
@@ -409,10 +403,13 @@ controls = [
When Vizro initially builds a filter that depends on parametrized dynamic data loading, data is loaded using the default argument values. This data is used to:
-* perform initial validation
-* check which data sources contain the specified `column` (unless `targets` is explicitly specified) and
-* find the type of selector to use (unless `selector` is explicitly specified).
+- perform initial validation
+- check which data sources contain the specified `column` (unless `targets` is explicitly specified) and
+- find the type of selector to use (unless `selector` is explicitly specified).
!!! note
-
When the value of a dynamic data parameter is changed by a dashboard user, the data underlying a dynamic filter can change. Currently this change affects page components such as `vm.Graph` but does not affect the available values shown in a dynamic filter, which only update on page refresh. This functionality will be coming soon!
+
+[databasic]: ../../assets/user_guides/data/data_pandas_dataframe.png
+[dynamicdata]: ../../assets/user_guides/data/dynamic_data.gif
+[parametrizeddynamicdata]: ../../assets/user_guides/data/parametrized_dynamic_data.gif
diff --git a/vizro-core/docs/pages/user-guides/extensions.md b/vizro-core/docs/pages/user-guides/extensions.md
index 2c7efc9ac..74a740448 100644
--- a/vizro-core/docs/pages/user-guides/extensions.md
+++ b/vizro-core/docs/pages/user-guides/extensions.md
@@ -2,64 +2,49 @@
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).
+- **[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.
+- **[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.
-* **[CSS customizations](#css-customizations)**. You can add custom CSS to any Vizro dashboard, enabling users to deviate from the default styling and create a unique look and feel for their dashboard.
-
-* **[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
+- **[CSS customizations](#css-customizations)**. You can add custom CSS to any Vizro dashboard, enabling users to deviate from the default styling and create a unique look and feel for their dashboard.
+- **[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
-
+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)).
+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.
-
+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).
+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
+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:
+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
@@ -93,14 +78,12 @@ enabling an interaction between data points in a scatter plot and the content of
## CSS customizations
-Vizro is opinionated about visual formatting, and some elements, such as the layout of the navigation and controls,
-are fixed. You can customize some settings such as background colors, fonts, and other styles via CSS overrides.
+Vizro is opinionated about visual formatting, and some elements, such as the layout of the navigation and controls, are fixed. You can customize some settings such as background colors, fonts, and other styles via CSS overrides.
For more information, see our documentation on [customizing CSS](custom-css.md)
## 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
+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)
diff --git a/vizro-core/docs/pages/user-guides/figure.md b/vizro-core/docs/pages/user-guides/figure.md
index 0589fad3b..03bfa412a 100644
--- a/vizro-core/docs/pages/user-guides/figure.md
+++ b/vizro-core/docs/pages/user-guides/figure.md
@@ -1,26 +1,19 @@
# How to use figures
-This guide shows you how to add any [Dash component](https://dash.plotly.com/#open-source-component-libraries) that needs to be reactive to [filter](filters.md) and [parameter](parameters.md) controls.
-If you want to add a static Dash component to your page, use [custom components](custom-components.md) instead.
+This guide shows you how to add any [Dash component](https://dash.plotly.com/#open-source-component-libraries) that needs to be reactive to [filter](filters.md) and [parameter](parameters.md) controls. If you want to add a static Dash component to your page, use [custom components](custom-components.md) instead.
-[`Figure`][vizro.models.Figure] provides a flexible foundation for all types of reactive Dash components in Vizro.
-The [`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] and [`AgGrid`][vizro.models.AgGrid] components are
-specific implementations of `Figure`. They serve as intuitive shortcuts, embedding behaviors and interactions specific
-to their purposes.
+[`Figure`][vizro.models.Figure] provides a flexible foundation for all types of reactive Dash components in Vizro. The [`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] and [`AgGrid`][vizro.models.AgGrid] components are specific implementations of `Figure`. They serve as intuitive shortcuts, embedding behaviors and interactions specific to their purposes.
-If these more specific models already achieve what you need then they should be used in preference to
-the more generic `Figure`. Remember that it is possible to supply [custom charts](custom-charts.md) to `Graph`
-and [custom tables](custom-tables.md) to `Table`.
+If these more specific models already achieve what you need then they should be used in preference to the more generic `Figure`. Remember that it is possible to supply [custom charts](custom-charts.md) to `Graph` and [custom tables](custom-tables.md) to `Table`.
-There are already a few figure functions you can reuse, see the section on [KPI cards](#key-performance-indicator-kpi-cards)
-for more details:
+There are already a few figure functions you can reuse, see the section on [KPI cards](#key-performance-indicator-kpi-cards) for more details:
- [`kpi_card`][vizro.figures.kpi_card]
- [`kpi_card_reference`][vizro.figures.kpi_card_reference]
The following flowchart shows what you need to consider when choosing which model to use:
-``` mermaid
+```mermaid
graph TD
first["`Does your desired component exist in Vizro, e.g. Graph, Table or AgGrid?`"]
specific-component([Use the specific component])
@@ -40,14 +33,12 @@ graph TD
classDef clickable color:#4051b5;
```
-
To add a `Figure` to your page:
1. Add the `Figure` model to the components argument of the [Page][vizro.models.Page] model.
-2. Use an existing figure function from [`vizro.figures`](../API-reference/figure-callables.md) and pass it to the `figure` argument of the `Figure` model.
+1. Use an existing figure function from [`vizro.figures`](../API-reference/figure-callables.md) and pass it to the `figure` argument of the `Figure` model.
!!! example "Use existing figure functions"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -99,40 +90,25 @@ To add a `Figure` to your page:
selector:
type: radio_items
layout:
- grid:
- [
- [0, -1, -1, -1],
- [-1, -1, -1, -1],
- [-1, -1, -1, -1],
- [-1, -1, -1, -1],
- [-1, -1, -1, -1],
- ]
+ grid: [[0, -1, -1, -1], [-1, -1, -1, -1], [-1, -1, -1, -1], [-1, -1, -1, -1],
+ [-1, -1, -1, -1]]
title: KPI card
```
- === "Result"
- [![Figure]][Figure]
-
- [Figure]: ../../assets/user_guides/figure/figure.png
+ === "Result"
+ [![Figure]][figure]
### Key Performance Indicator (KPI) cards
-A KPI card is a dynamic card that can display a single value, but optionally, can also include a title, icon, and reference value.
-It is a common visual component to display key metrics in a dashboard. Vizro supports two pre-defined KPI card functions:
-- [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card): A KPI card that shows a single value found
-by performing an aggregation function (by default, `sum`) over a specified column.
-Required arguments are `data_frame` and `value_column`.
+A KPI card is a dynamic card that can display a single value, but optionally, can also include a title, icon, and reference value. It is a common visual component to display key metrics in a dashboard. Vizro supports two pre-defined KPI card functions:
-- [`kpi_card_with_reference`](../API-reference/figure-callables.md#vizro.figures.kpi_card_reference): A KPI card that shows a single value
-and a delta comparison to a reference value found by performing an aggregation function (by default, `sum`) over the specified columns.
-Required arguments are `data_frame`, `value_column` and `reference_column`.
+- [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card): A KPI card that shows a single value found by performing an aggregation function (by default, `sum`) over a specified column. Required arguments are `data_frame` and `value_column`.
-As described in the [API reference](../API-reference/figure-callables.md) and illustrated in the below example, these
-functions have several arguments to customize your KPI cards. If you require a level of customization that is not
-possible with the built-in functions then you can create a [custom figure](custom-figures.md).
+- [`kpi_card_with_reference`](../API-reference/figure-callables.md#vizro.figures.kpi_card_reference): A KPI card that shows a single value and a delta comparison to a reference value found by performing an aggregation function (by default, `sum`) over the specified columns. Required arguments are `data_frame`, `value_column` and `reference_column`.
-!!! example "KPI card variations"
+As described in the [API reference](../API-reference/figure-callables.md) and illustrated in the below example, these functions have several arguments to customize your KPI cards. If you require a level of customization that cannot be done with the built-in functions then you can create a [custom figure](custom-figures.md).
+!!! example "KPI card variations"
=== "app.py"
```{.python pycafe-link}
import pandas as pd
@@ -258,8 +234,8 @@ possible with the built-in functions then you can create a [custom figure](custo
value_column: Actual
reference_column: Reference
title: KPI reference with formatting
- value_format: "{value:.2f}€"
- reference_format: "{delta:+.2f}€ vs. last year ({reference:.2f}€)"
+ value_format: '{value:.2f}€'
+ reference_format: '{delta:+.2f}€ vs. last year ({reference:.2f}€)'
type: figure
- figure:
_target_: kpi_card_reference
@@ -276,7 +252,9 @@ possible with the built-in functions then you can create a [custom figure](custo
grid: [[0, 1, 2, 3], [4, 5, 6, 7], [-1, -1, -1, -1], [-1, -1, -1, -1]]
title: KPI cards
```
+
=== "Result"
- [![KPICards]][KPICards]
+ [![KPICards]][kpicards]
- [KPICards]: ../../assets/user_guides/figure/kpi_cards.png
+[figure]: ../../assets/user_guides/figure/figure.png
+[kpicards]: ../../assets/user_guides/figure/kpi_cards.png
diff --git a/vizro-core/docs/pages/user-guides/filters.md b/vizro-core/docs/pages/user-guides/filters.md
index bc3649178..8228ecbe7 100644
--- a/vizro-core/docs/pages/user-guides/filters.md
+++ b/vizro-core/docs/pages/user-guides/filters.md
@@ -2,8 +2,7 @@
This guide shows you how to add filters to your dashboard. One main way to interact with the charts/components on your page is by filtering the underlying data. A filter selects a subset of rows of a component's underlying DataFrame which alters the appearance of that component on the page.
-The [`Page`][vizro.models.Page] model accepts the `controls` argument, where you can enter a [`Filter`][vizro.models.Filter] model.
-This model enables the automatic creation of [selectors](selectors.md) (for example, `Dropdown` or `RangeSlider`) that operate on the charts/components on the screen.
+The [`Page`][vizro.models.Page] model accepts the `controls` argument, where you can enter a [`Filter`][vizro.models.Filter] model. This model enables the automatic creation of [selectors](selectors.md) (for example, `Dropdown` or `RangeSlider`) that operate on the charts/components on the screen.
By default, filters that control components with [dynamic data](data.md#dynamic-data) are [dynamically updated](data.md#filters) when the underlying data changes while the dashboard is running.
@@ -12,7 +11,7 @@ By default, filters that control components with [dynamic data](data.md#dynamic-
To add a filter to your page, do the following:
1. add the [`Filter`][vizro.models.Filter] model into the `controls` argument of the [`Page`][vizro.models.Page] model
-2. configure the `column` argument, which denotes the target column to be filtered
+1. configure the `column` argument, which denotes the target column to be filtered
You can also set `targets` to specify which components on the page the filter should apply to. If this is not explicitly set then `targets` defaults to all components on the page whose data source includes `column`.
@@ -39,6 +38,7 @@ You can also set `targets` to specify which components on the page the filter sh
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -57,17 +57,15 @@ You can also set `targets` to specify which components on the page the filter sh
type: filter
title: My first page
```
- === "Result"
- [![Filter]][Filter]
-
- [Filter]: ../../assets/user_guides/control/control1.png
+ === "Result"
+ [![Filter]][filter]
The selector is configured automatically based on the target column type data as follows:
- - Categorical data uses [`vm.Dropdown(multi=True)`][vizro.models.Dropdown] where `options` is the set of unique values found in `column` across all the data sources of components in `targets`.
- - [Numerical data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_numeric_dtype.html) uses [`vm.RangeSlider`][vizro.models.RangeSlider] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`.
- - [Temporal data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_datetime64_any_dtype.html) uses [`vm.DatePicker(range=True)`][vizro.models.DatePicker] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`. A column can be converted to this type with [pandas.to_datetime](https://pandas.pydata.org/docs/reference/api/pandas.to_datetime.html).
+- Categorical data uses [`vm.Dropdown(multi=True)`][vizro.models.Dropdown] where `options` is the set of unique values found in `column` across all the data sources of components in `targets`.
+- [Numerical data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_numeric_dtype.html) uses [`vm.RangeSlider`][vizro.models.RangeSlider] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`.
+- [Temporal data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_datetime64_any_dtype.html) uses [`vm.DatePicker(range=True)`][vizro.models.DatePicker] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`. A column can be converted to this type with [pandas.to_datetime](https://pandas.pydata.org/docs/reference/api/pandas.to_datetime.html).
The following example demonstrates these default selector types.
@@ -107,6 +105,7 @@ The following example demonstrates these default selector types.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -129,15 +128,13 @@ The following example demonstrates these default selector types.
type: filter
title: My first page
```
- === "Result"
- [![Filter]][Filter]
- [Filter]: ../../assets/user_guides/selectors/default_filter_selectors.png
+ === "Result"
+ [![Filter]][filter]
## Change selector
-If you want to have a different selector for your filter, you can give the `selector` argument of the [`Filter`][vizro.models.Filter] a different selector model.
-Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropdown`][vizro.models.Dropdown], [`RadioItems`][vizro.models.RadioItems], [`RangeSlider`][vizro.models.RangeSlider], [`Slider`][vizro.models.Slider], and [`DatePicker`][vizro.models.DatePicker].
+If you want to have a different selector for your filter, you can give the `selector` argument of the [`Filter`][vizro.models.Filter] a different selector model. Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropdown`][vizro.models.Dropdown], [`RadioItems`][vizro.models.RadioItems], [`RangeSlider`][vizro.models.RangeSlider], [`Slider`][vizro.models.Slider], and [`DatePicker`][vizro.models.DatePicker].
!!! example "Filter with different selector"
=== "app.py"
@@ -162,6 +159,7 @@ Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropd
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -181,11 +179,9 @@ Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropd
type: filter
title: My first page
```
- === "Result"
-
- [![Selector]][Selector]
- [Selector]: ../../assets/user_guides/control/control2.png
+ === "Result"
+ [![Selector]][selector]
## Further customization
@@ -220,6 +216,7 @@ Below is an advanced example where we only target one page component, and where
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -244,17 +241,19 @@ Below is an advanced example where we only target one page component, and where
controls:
- column: petal_length
targets:
- - scatter_chart
+ - scatter_chart
selector:
step: 1
type: range_slider
type: filter
title: My first page
```
- === "Result"
-
- [![Advanced]][Advanced]
- [Advanced]: ../../assets/user_guides/control/control3.png
+ === "Result"
+ [![Advanced]][advanced]
To further customize selectors, see our [how-to-guide on creating custom components](custom-components.md).
+
+[advanced]: ../../assets/user_guides/control/control3.png
+[filter]: ../../assets/user_guides/control/control1.png
+[selector]: ../../assets/user_guides/control/control2.png
diff --git a/vizro-core/docs/pages/user-guides/graph.md b/vizro-core/docs/pages/user-guides/graph.md
index 36c670997..1c3ffc8bc 100755
--- a/vizro-core/docs/pages/user-guides/graph.md
+++ b/vizro-core/docs/pages/user-guides/graph.md
@@ -6,25 +6,18 @@ The [`Graph`][vizro.models.Graph] model is the most used component in many dashb
To add a [`Graph`][vizro.models.Graph] to your page, do the following:
-1. insert the [`Graph`][vizro.models.Graph] model into the `components` argument of the
-[`Page`][vizro.models.Page] model
-2. enter any of the currently available charts of the open source library [`plotly.express`](https://plotly.com/python/plotly-express/) into the `figure` argument
+1. insert the [`Graph`][vizro.models.Graph] model into the `components` argument of the [`Page`][vizro.models.Page] model
+1. enter any of the currently available charts of the open source library [`plotly.express`](https://plotly.com/python/plotly-express/) into the `figure` argument
!!! note
+ To use the [`plotly.express`](https://plotly.com/python/plotly-express/) chart in a Vizro dashboard, you need to import it as `import vizro.plotly.express as px`. This leaves any of the [`plotly.express`](https://plotly.com/python/plotly-express/) functionality untouched yet enables _direct insertion_ into the [`Graph`][vizro.models.Graph] model _as is_.
- In order to use the [`plotly.express`](https://plotly.com/python/plotly-express/) chart in a Vizro dashboard, you need to import it as `import vizro.plotly.express as px`.
- This leaves any of the [`plotly.express`](https://plotly.com/python/plotly-express/) functionality untouched, but allows _direct insertion_ into the [`Graph`][vizro.models.Graph] model _as is_.
-
- Note also that the `plotly.express` chart needs to have a `data_frame` argument. In case you require a chart without
- a `data_frame` argument (for example, the [`imshow` chart](https://plotly.com/python/imshow/)), refer to our
- [guide on custom charts](custom-charts.md).
-
+ Note also that the `plotly.express` chart needs to have a `data_frame` argument. In case you require a chart without a `data_frame` argument (for example, the [`imshow` chart](https://plotly.com/python/imshow/)), refer to our [guide on custom charts](custom-charts.md).
## Insert Plotly chart
!!! example "Graph"
=== "app.py"
-
```{.python pycafe-link}
import vizro.models as vm
import vizro.plotly.express as px
@@ -47,25 +40,24 @@ To add a [`Graph`][vizro.models.Graph] to your page, do the following:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: scatter_matrix
- color: species
- data_frame: iris
- dimensions: ["sepal_length", "sepal_width", "petal_length", "petal_width"]
- type: graph
- title: My first page
+ - components:
+ - figure:
+ _target_: scatter_matrix
+ color: species
+ data_frame: iris
+ dimensions: [sepal_length, sepal_width, petal_length, petal_width]
+ type: graph
+ title: My first page
```
- === "Result"
- [![Graph]][Graph]
-
- [Graph]: ../../assets/user_guides/components/graph.png
+ === "Result"
+ [![Graph]][graph]
In the Python example we directly inserted the pandas DataFrame `df` into `figure=px.scatter_matrix(df, ...)`. This is [one way to supply data to a chart](data.md#supply-directly). For the YAML version, we [refer to the data source by name](data.md#reference-by-name) as `data_frame: iris`. For a full explanation of the different methods you can use to send data to your dashboard, see [our guide to using data in Vizro](data.md).
@@ -73,31 +65,24 @@ In the Python example we directly inserted the pandas DataFrame `df` into `figur
You will need to create a custom chart if you want to customize the Plotly chart beyond a function call, for example by:
-* using post-update methods like `update_layout`, `update_xaxes`, `update_traces`, or
-* by creating a custom `plotly.graph_objects.Figure()` object and manually adding traces with `add_trace`.
-
-For more details, refer to our [user guide on custom chart](custom-charts.md) and the
-[Plotly documentation on updating figures](https://plotly.com/python/creating-and-updating-figures/).
+- using post-update methods like `update_layout`, `update_xaxes`, `update_traces`, or
+- by creating a custom `plotly.graph_objects.Figure()` object and manually adding traces with `add_trace`.
+For more details, refer to our [user guide on custom chart](custom-charts.md) and the [Plotly documentation on updating figures](https://plotly.com/python/creating-and-updating-figures/).
## Add title, header, and footer
-The [`Graph`][vizro.models.Graph] accepts a `title`, `header` and `footer` argument. This is useful for providing
-context to the data being displayed, or for adding a description of the data.
+The [`Graph`][vizro.models.Graph] accepts a `title`, `header` and `footer` argument. This is useful for context on the data being displayed, or for adding a description of the data.
- **title**: Displayed as an [H3 header](https://dash.plotly.com/dash-html-components/h3), useful for summarizing the main topic or insight of the component.
- **header**: Accepts markdown text, ideal for extra descriptions, subtitles, or detailed data insights.
- **footer**: Accepts markdown text, commonly used for citing data sources, providing information on the last update, or adding disclaimers.
-
!!! note
-
- Although you can directly provide a `title` to the Plotly Express chart, we recommend using `Graph.title` for
- proper alignment with other components on the screen.
+ Although you can directly give a `title` to the Plotly Express chart, we recommend using `Graph.title` for proper alignment with other components on the screen.
!!! example "Formatted Graph"
=== "app.py"
-
```{.python pycafe-link}
import vizro.models as vm
@@ -126,31 +111,34 @@ context to the data being displayed, or for adding a description of the data.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: scatter
- x: sepal_width
- y: sepal_length
- color: species
- data_frame: iris
- title: Relationships between Sepal Width and Sepal Length
- header: |
- Each point in the scatter plot represents one of the 150 iris flowers, with colors indicating their
- types. The Setosa type is easily identifiable by its short and wide sepals.
-
- However, there is still overlap between the Versicolor and Virginica types when considering only sepal
- width and length.
- footer: |
- SOURCE: **Plotly iris data set, 2024**
- type: graph
- title: Formatted Graph
+ - components:
+ - figure:
+ _target_: scatter
+ x: sepal_width
+ y: sepal_length
+ color: species
+ data_frame: iris
+ title: Relationships between Sepal Width and Sepal Length
+ header: |
+ Each point in the scatter plot represents one of the 150 iris flowers, with colors indicating their
+ types. The Setosa type is easily identifiable by its short and wide sepals.
+
+ However, there is still overlap between the Versicolor and Virginica types when considering only sepal
+ width and length.
+ footer: |
+ SOURCE: **Plotly iris data set, 2024**
+ type: graph
+ title: Formatted Graph
```
+
=== "Result"
- [![FormattedGraph]][FormattedGraph]
+ [![FormattedGraph]][formattedgraph]
- [FormattedGraph]: ../../assets/user_guides/components/formatted_graph.png
+[formattedgraph]: ../../assets/user_guides/components/formatted_graph.png
+[graph]: ../../assets/user_guides/components/graph.png
diff --git a/vizro-core/docs/pages/user-guides/install.md b/vizro-core/docs/pages/user-guides/install.md
index 4d4c01239..6a07911e5 100644
--- a/vizro-core/docs/pages/user-guides/install.md
+++ b/vizro-core/docs/pages/user-guides/install.md
@@ -8,8 +8,8 @@ We recommend that you create a virtual environment for each Vizro project you wo
## Prerequisites to working locally
-* **Python**: Vizro supports macOS, Linux, and Windows. It works with Python 3.9 and later.
-* **Virtual environment**: You specify the version of Python to use with Vizro when you set up the virtual environment. See the following references to learn more about [Python virtual environments](https://realpython.com/python-virtual-environments-a-primer/), [Conda virtual environments](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#starting-conda) or [watch an explainer video about them](https://youtu.be/YKfAwIItO7M).
+- **Python**: Vizro supports macOS, Linux, and Windows. It works with Python 3.9 and later.
+- **Virtual environment**: You specify the version of Python to use with Vizro when you set up the virtual environment. See the following references to learn more about [Python virtual environments](https://realpython.com/python-virtual-environments-a-primer/), [Conda virtual environments](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#starting-conda) or [watch an explainer video about them](https://youtu.be/YKfAwIItO7M).
### How to create a virtual environment for your Vizro project
diff --git a/vizro-core/docs/pages/user-guides/kedro-data-catalog.md b/vizro-core/docs/pages/user-guides/kedro-data-catalog.md
index 0e2b0954e..ce4b060fa 100644
--- a/vizro-core/docs/pages/user-guides/kedro-data-catalog.md
+++ b/vizro-core/docs/pages/user-guides/kedro-data-catalog.md
@@ -3,6 +3,7 @@
This page describes how to integrate Vizro with [Kedro](https://docs.kedro.org/en/stable/index.html), an open-source Python framework to create reproducible, maintainable, and modular data science code. For Pandas datasets registered in a Kedro data catalog, Vizro provides a convenient way to visualize them.
## Installation
+
If you already have Kedro installed then you do not need to install any extra dependencies. If you do not have Kedro installed then you should run:
```bash
@@ -10,7 +11,9 @@ pip install vizro[kedro]
```
## Use datasets from the Kedro Data Catalog
+
`vizro.integrations.kedro` provides functions to help generate and process a [Kedro Data Catalog](https://docs.kedro.org/en/stable/data/index.html). Given a Kedro Data Catalog `catalog`, the general pattern to add datasets into the Vizro data manager is:
+
```python
from vizro.integrations import kedro as kedro_integration
from vizro.managers import data_manager
@@ -25,15 +28,14 @@ This imports all datasets of type [`kedro_datasets.pandas`](https://docs.kedro.o
The `catalog` variable may have been created in a number of different ways:
1. Kedro project path. Vizro exposes a helper function `vizro.integrations.kedro.catalog_from_project` to generate a `catalog` given the path to a Kedro project.
-2. [Kedro Jupyter session](https://docs.kedro.org/en/stable/notebooks_and_ipython/kedro_and_notebooks.html). This automatically exposes `catalog`.
-3. Data Catalog configuration file (`catalog.yaml`). This can create a `catalog` entirely independently of a Kedro project using [`kedro.io.DataCatalog.from_config`](https://docs.kedro.org/en/stable/kedro.io.DataCatalog.html#kedro.io.DataCatalog.from_config).
+1. [Kedro Jupyter session](https://docs.kedro.org/en/stable/notebooks_and_ipython/kedro_and_notebooks.html). This automatically exposes `catalog`.
+1. Data Catalog configuration file (`catalog.yaml`). This can create a `catalog` entirely independently of a Kedro project using [`kedro.io.DataCatalog.from_config`](https://docs.kedro.org/en/stable/kedro.io.DataCatalog.html#kedro.io.DataCatalog.from_config).
The full code for these different cases is given below.
!!! example "Import a Kedro Data Catalog into the Vizro data manager"
-
=== "app.py (Kedro project path)"
- ```py
+ ```python
from vizro.integrations import kedro as kedro_integration
from vizro.managers import data_manager
@@ -43,16 +45,18 @@ The full code for these different cases is given below.
for dataset_name, dataset in kedro_integration.datasets_from_catalog(catalog).items():
data_manager[dataset_name] = dataset
```
+
=== "app.ipynb (Kedro Jupyter session)"
- ```py
+ ```python
from vizro.managers import data_manager
for dataset_name, dataset in kedro_integration.datasets_from_catalog(catalog).items():
data_manager[dataset_name] = dataset
```
+
=== "app.py (Data Catalog configuration file)"
- ```py
+ ```python
from kedro.io import DataCatalog
import yaml
diff --git a/vizro-core/docs/pages/user-guides/layouts.md b/vizro-core/docs/pages/user-guides/layouts.md
index 8361560db..af66ec301 100644
--- a/vizro-core/docs/pages/user-guides/layouts.md
+++ b/vizro-core/docs/pages/user-guides/layouts.md
@@ -3,11 +3,10 @@
The [`Page`][vizro.models.Page] model accepts a `layout` argument that enables custom arrangement of charts and components on the screen. This guide shows how to customize the grid specifications in the [`Layout`][vizro.models.Layout].
## The default layout
-The `layout` argument of the [`Page`][vizro.models.Page] model is optional. If no layout is specified, all charts/components are automatically [**stacked vertically**](layouts.md#vertical-and-horizontal-stacking) on the page in one column.
-If you are happy with that arrangement, you can create your charts/components without providing a [`Layout`][vizro.models.Layout].
-!!! example "Default Layout"
+The `layout` argument of the [`Page`][vizro.models.Page] model is optional. If no layout is specified, all charts/components are automatically [**stacked vertically**](layouts.md#vertical-and-horizontal-stacking) on the page in one column. If you are happy with that arrangement, you can create your charts/components without providing a [`Layout`][vizro.models.Layout].
+!!! example "Default Layout"
=== "app.py"
```{.python pycafe-link}
from vizro import Vizro
@@ -23,35 +22,33 @@ If you are happy with that arrangement, you can create your charts/components wi
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- title: two_left
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ title: two_left
```
- === "Result"
- [![Layout]][Layout]
-
- [Layout]: ../../assets/user_guides/layout/two_left.png
-
+ === "Result"
+ [![Layout]][layout]
## Configure the grid
+
To customize the grid arrangement, configure the `grid` parameter of the [`Layout`][vizro.models.Layout] model.
The example below shows an example of a valid `grid`:
```python title="Basic example"
-grid = [[0, 1],
- [0, 2]]
+grid = [[0, 1], [0, 2]]
```
- The `grid` must be provided as `list[list[int]]` (for example, `grid = [[0, 1], [0, 2]]`).
@@ -64,16 +61,12 @@ grid = [[0, 1],
- The area spanned by a chart/component in the grid must be rectangular.
- The grid can be arbitrarily large, allowing arbitrarily granular control of the grid.
-
## Vertical and horizontal stacking
+
As described above, when no `Layout` is specified, components are presented **vertically** as a single-column stack. If you have three components, the default `Layout.grid` will be as follows, with three equally sized rows, each containing a component spanning the entire width:
```python title="Vertical stacking"
-grid = [
- [0],
- [1],
- [2]
- ]
+grid = [[0], [1], [2]]
```
To present components **horizontally** in one row:
@@ -89,8 +82,8 @@ This defines a single row that occupies the entire width and height, divided int
## Grid - basic example
-!!! example "Grid Arrangement - Basic Example"
+!!! example "Grid Arrangement - Basic Example"
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -109,39 +102,37 @@ This defines a single row that occupies the entire width and height, divided int
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- - text: |
- # Component 2
- type: card
- layout:
- grid: [[0, 1], [0, 2]]
- title: one_left_two_right
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ layout:
+ grid: [[0, 1], [0, 2]]
+ title: one_left_two_right
```
- === "Result"
- [![Grid]][Grid]
- [Grid]: ../../assets/user_guides/layout/one_left_two_right.png
+ === "Result"
+ [![Grid]][grid]
## Grid - advanced example
If you want to divide the grid into subgrids with finer control over these, you can use [`Containers`](container.md). See our section on [when to use `Containers` vs. `Page.layout`](container.md#when-to-use-containers) for more information.
-The `Layout` provides full control over the arrangement of top-level components within a page,
-allowing arbitrarily granular control of the grid by creating larger grids.
+The `Layout` provides full control over the arrangement of top-level components within a page, allowing arbitrarily granular control of the grid by creating larger grids.
!!! example "Grid Arrangement - Advanced Example"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -208,6 +199,7 @@ allowing arbitrarily granular control of the grid by creating larger grids.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -260,44 +252,44 @@ allowing arbitrarily granular control of the grid by creating larger grids.
grid: [[0, 1, 3, 4], [2, 2, 3, 4]]
title: Custom Layout - Advanced Example
```
- === "Result"
- [![GridAdv]][GridAdv]
- [GridAdv]: ../../assets/user_guides/layout/grid_advanced.png
+ === "Result"
+ [![GridAdv]][gridadv]
## Custom layout examples
+
Here is a reference table of example layouts:
+
one row with one component, second row with two components stacked horizontally
-| Layout needed | Grid | Code |
-|--------------------------------|----------------------------|-------------------------------------------------------------------------------------|
-| | | `layout=vm.Layout(grid=[[0]])` |
-| | | `layout=vm.Layout(grid=[[0],[1]])` |
-| | | `layout=vm.Layout(grid=[[0,1]])` |
-| | | `layout=vm.Layout(grid=[[0],[1],[2]])` or
`layout=None` |
-| | | `layout=vm.Layout(grid=[[0,1],[0,2]])` |
-| | | `layout=vm.Layout(grid=[[0,0],[1,2]])` |
-| | | `layout=vm.Layout(grid=[[0,1],[2,2]])` |
-| | | `layout=vm.Layout(grid=[[0,1],[0,2],[0,3]])` |
-| | | `layout=vm.Layout(grid=[[0,1],[2,3]])` |
-| | | `layout=vm.Layout(grid=[[0,3],[1,3],[2,3]])` |
-| | | `layout=vm.Layout(grid=[[0,0,0],[1,2,3]])` |
-| | | `layout=vm.Layout(grid=[[0,1,2],[3,3,3]])` |
+| Layout needed | Grid | Code |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| | | `layout=vm.Layout(grid=[[0]])` |
+| | | `layout=vm.Layout(grid=[[0],[1]])` |
+| | | `layout=vm.Layout(grid=[[0,1]])` |
+| | | `layout=vm.Layout(grid=[[0],[1],[2]])` or
`layout=None` |
+| | | `layout=vm.Layout(grid=[[0,1],[0,2]])` |
+| | | `layout=vm.Layout(grid=[[0,0],[1,2]])` |
+| | | `layout=vm.Layout(grid=[[0,1],[2,2]])` |
+| | | `layout=vm.Layout(grid=[[0,1],[0,2],[0,3]])` |
+| | | `layout=vm.Layout(grid=[[0,1],[2,3]])` |
+| | | `layout=vm.Layout(grid=[[0,3],[1,3],[2,3]])` |
+| | | `layout=vm.Layout(grid=[[0,0,0],[1,2,3]])` |
+| | | `layout=vm.Layout(grid=[[0,1,2],[3,3,3]])` |
## Add empty sections to the grid
+
One approach to organize the dashboard's layout involves integrating empty sections by specifying `-1` within the grid layout.
```python title="Example"
-grid = [[0, 1, -1],
- [0, 2, -1]]
+grid = [[0, 1, -1], [0, 2, -1]]
```
!!! example "Adding Empty Spaces"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -316,38 +308,38 @@ grid = [[0, 1, -1],
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- - text: |
- # Component 2
- type: card
- layout:
- grid: [[0, 1, -1], [0, 2, -1]]
- title: Adding empty spaces
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ layout:
+ grid: [[0, 1, -1], [0, 2, -1]]
+ title: Adding empty spaces
```
- === "Result"
- [![GridEmpty]][GridEmpty]
- [GridEmpty]: ../../assets/user_guides/layout/layout_empty_spaces.png
+ === "Result"
+ [![GridEmpty]][gridempty]
## Control the scroll behavior
+
By default, the grid fits all charts/components on the screen. This can lead to distortions such that the chart/component looks squashed. To control the scroll behavior, you can specify the following:
- `row_min_height`: Sets a chart/component's minimum height. Defaults to 0px.
- `col_min_width`: Sets a chart/component's minimum width. Defaults to 0px.
!!! example "Activate Scrolling"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -371,59 +363,63 @@ By default, the grid fits all charts/components on the screen. This can lead to
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- - text: |
- # Component 2
- type: card
- - text: |
- # Component 2
- type: card
- - text: |
- # Component 4
- type: card
- - text: |
- # Component 5
- type: card
- - text: |
- # Component 6
- type: card
- - text: |
- # Component 7
- type: card
- layout:
- grid: [[0], [1], [2], [3], [4], [5], [6], [7]]
- row_min_height: 240px
- title: Activate scrolling
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ - text: |
+ # Component 4
+ type: card
+ - text: |
+ # Component 5
+ type: card
+ - text: |
+ # Component 6
+ type: card
+ - text: |
+ # Component 7
+ type: card
+ layout:
+ grid: [[0], [1], [2], [3], [4], [5], [6], [7]]
+ row_min_height: 240px
+ title: Activate scrolling
```
- === "Result"
- [![GridScroll]][GridScroll]
-
- [GridScroll]: ../../assets/user_guides/layout/grid_scroll.png
+ === "Result"
+ [![GridScroll]][gridscroll]
## Further customization
-For further customization, such as changing the gap between row and column, refer to the
-documentation of the [`Layout`][vizro.models.Layout] model.
+
+For further customization, such as changing the gap between row and column, refer to the documentation of the [`Layout`][vizro.models.Layout] model.
## Alternative layout approaches
+
In general, any arbitrarily granular layout can already be achieved using [`Page.layout`](layouts.md) alone and is our recommended approach if you want to arrange components on a page with consistent row and/or column spacing.
!!! note "Alternative layout approaches: `Tabs` and `Containers`"
-
- [`Tabs`][vizro.models.Tabs] and [`Containers`][vizro.models.Container] provide an alternative approach to customize your page layout.
- For example, if you want to have more granular control and break the overall page grid into subgrids, see our [user guide on Containers](container.md).
+ [`Tabs`][vizro.models.Tabs] and [`Containers`][vizro.models.Container] offer an alternative approach to customize your page layout. For example, if you want to have more granular control and break the overall page grid into subgrids, see our [user guide on Containers](container.md).
If you want to display multiple containers on one page by putting them into the same screen space, and letting the user switch between them, see our [user guide on Tabs](tabs.md).
{ width="500" }
+
+[grid]: ../../assets/user_guides/layout/one_left_two_right.png
+[gridadv]: ../../assets/user_guides/layout/grid_advanced.png
+[gridempty]: ../../assets/user_guides/layout/layout_empty_spaces.png
+[gridscroll]: ../../assets/user_guides/layout/grid_scroll.png
+[layout]: ../../assets/user_guides/layout/two_left.png
diff --git a/vizro-core/docs/pages/user-guides/navigation.md b/vizro-core/docs/pages/user-guides/navigation.md
index 41c6bb9dc..75a661470 100644
--- a/vizro-core/docs/pages/user-guides/navigation.md
+++ b/vizro-core/docs/pages/user-guides/navigation.md
@@ -2,8 +2,7 @@
This guide shows you how to use and customize the navigation that appears on the left of your dashboard.
-The [`Dashboard`][vizro.models.Dashboard] model accepts a `navigation` argument, where you can enter a [`Navigation`][vizro.models.Navigation] model. This enables you to group pages together and customize how they appear in your navigation.
-The dashboard includes a collapsible side panel that users can minimize or expand by a button click. The collapse button, located in the top right corner of the side panel, is visible by default for user convenience.
+The [`Dashboard`][vizro.models.Dashboard] model accepts a `navigation` argument, where you can enter a [`Navigation`][vizro.models.Navigation] model. This enables you to group pages together and customize how they appear in your navigation. The dashboard includes a collapsible side panel that users can minimize or expand by a button click. The collapse button, located in the top right corner of the side panel, is visible by default for user convenience.
## Use the default navigation
@@ -56,8 +55,8 @@ By default, if the `navigation` argument is not specified, Vizro creates a navig
type: graph
title: My first page
- components:
- - text: My text here
- type: card
+ - text: My text here
+ type: card
title: My second page
- components:
- figure:
@@ -69,10 +68,9 @@ By default, if the `navigation` argument is not specified, Vizro creates a navig
type: graph
title: My third page
```
- === "Result"
- [![DefaultNavigation]][DefaultNavigation]
- [DefaultNavigation]: ../../assets/user_guides/navigation/default_navigation.png
+ === "Result"
+ [![DefaultNavigation]][defaultnavigation]
## Include a subset of pages
@@ -132,17 +130,15 @@ To include only some of your dashboard pages in your navigation then list them i
- My first page
- My second page
```
- === "Result"
- [![OnlySomePages]][OnlySomePages]
- [OnlySomePages]: ../../assets/user_guides/navigation/only_some_pages.png
+ === "Result"
+ [![OnlySomePages]][onlysomepages]
## Group pages
You can also group your pages together by specifying `pages` as a dictionary:
!!! example "Grouping pages"
-
=== "snippet.py"
```py
# page_1, page_2, page_3 defined as in default example
@@ -154,7 +150,6 @@ You can also group your pages together by specifying `pages` as a dictionary:
```
=== "app.py"
-
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -187,6 +182,7 @@ You can also group your pages together by specifying `pages` as a dictionary:
)
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -200,18 +196,15 @@ You can also group your pages together by specifying `pages` as a dictionary:
Group B:
- My third page
```
- === "Result"
- [![GroupedNavigation]][GroupedNavigation]
-
- [GroupedNavigation]: ../../assets/user_guides/navigation/grouped_navigation.png
+ === "Result"
+ [![GroupedNavigation]][groupednavigation]
## Use a navigation bar with icons
Another way to group together pages in the navigation is to use a [`NavBar`][vizro.models.NavBar] with icons. The simplest way to use this is to change the `nav_selector` specified in [`Navigation`][vizro.models.Navigation]:
!!! example "Using `NavBar`"
-
=== "snippet.py"
```py
# page_1, page_2, page_3 defined as in default example
@@ -223,8 +216,8 @@ Another way to group together pages in the navigation is to use a [`NavBar`][viz
)
Vizro().build(dashboard).run()
```
- === "app.py"
+ === "app.py"
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -276,14 +269,11 @@ Another way to group together pages in the navigation is to use a [`NavBar`][viz
nav_selector:
type: nav_bar
```
- === "Result"
- [![NavBar]][NavBar]
-
- [NavBar]: ../../assets/user_guides/navigation/nav_bar.png
+ === "Result"
+ [![NavBar]][navbar]
-Here, the first level of the navigation hierarchy ("Group A" and "Group B") is represented by an icon in a navigation bar, and the second level of the navigation (the pages) is represented by an accordion.
-By default, the set of icons used are the [`filter` icons from the Google Material icons library](https://fonts.google.com/icons?icon.query=filter). The icon label ("Group A" and "Group B") appears as a tooltip on hovering over the icon.
+Here, the first level of the navigation hierarchy ("Group A" and "Group B") is represented by an icon in a navigation bar, and the second level of the navigation (the pages) is represented by an accordion. By default, the set of icons used are the [`filter` icons from the Google Material icons library](https://fonts.google.com/icons?icon.query=filter). The icon label ("Group A" and "Group B") appears as a tooltip on hovering over the icon.
## Customize the navigation bar
@@ -314,7 +304,6 @@ The same configuration for [grouping pages](#group-pages) applies inside a `NavL
```
=== "app.py"
-
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -375,10 +364,9 @@ The same configuration for [grouping pages](#group-pages) applies inside a `NavL
Group B:
- My third page
```
- === "Result"
- [![AccordionInsideNavBar]][AccordionInsideNavBar]
- [AccordionInsideNavBar]: ../../assets/user_guides/navigation/accordion_inside_nav_bar.png
+ === "Result"
+ [![AccordionInsideNavBar]][accordioninsidenavbar]
You can alter the icons used by specifying the name of the icon in the [Google Material icons library](https://fonts.google.com/icons):
@@ -402,8 +390,8 @@ You can alter the icons used by specifying the name of the icon in the [Google M
),
)
```
- === "app.py"
+ === "app.py"
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -468,7 +456,13 @@ You can alter the icons used by specifying the name of the icon in the [Google M
pages:
- My third page
```
- === "Result"
- [![CustomIcons]][CustomIcons]
- [CustomIcons]: ../../assets/user_guides/navigation/custom_icons.png
+ === "Result"
+ [![CustomIcons]][customicons]
+
+[accordioninsidenavbar]: ../../assets/user_guides/navigation/accordion_inside_nav_bar.png
+[customicons]: ../../assets/user_guides/navigation/custom_icons.png
+[defaultnavigation]: ../../assets/user_guides/navigation/default_navigation.png
+[groupednavigation]: ../../assets/user_guides/navigation/grouped_navigation.png
+[navbar]: ../../assets/user_guides/navigation/nav_bar.png
+[onlysomepages]: ../../assets/user_guides/navigation/only_some_pages.png
diff --git a/vizro-core/docs/pages/user-guides/pages.md b/vizro-core/docs/pages/user-guides/pages.md
index 7ae944e9b..71e01e9f9 100644
--- a/vizro-core/docs/pages/user-guides/pages.md
+++ b/vizro-core/docs/pages/user-guides/pages.md
@@ -1,7 +1,6 @@
# How to use pages
-This guide shows you how to add pages to your dashboard and customize the URL paths if needed.
-A [`Page`][vizro.models.Page] lets you place and arrange your dashboard content (for example, chart/components, tables, and text)
-and configure your dashboard interactions (such as filters and parameters).
+
+This guide shows you how to add pages to your dashboard and customize the URL paths if needed. A [`Page`][vizro.models.Page] lets you place and arrange your dashboard content (for example, chart/components, tables, and text) and configure your dashboard interactions (such as filters and parameters).
The [`Dashboard`][vizro.models.Dashboard] model accepts the `pages` argument, where you can insert your [`Page`][vizro.models.Page].
@@ -10,19 +9,19 @@ The [`Dashboard`][vizro.models.Dashboard] model accepts the `pages` argument, wh
A [`Page`][vizro.models.Page] is split up into four main containers:
1. The **navigation container** where you can customize your `navigation` (see [Dashboard](dashboard.md) and [Navigation](navigation.md) for more information). Note that the navigation container needs to be configured via the Dashboard.
-2. The **control container** where you can add your `controls` (see [Filters](filters.md) or [Parameters](parameters.md)) to interact with the dashboard
-3. The **page header** that contains the page title and the theme toggle switch button
-4. The **component container** where you can add your [components](components.md) to visualize your data
+1. The **control container** where you can add your `controls` (see [Filters](filters.md) or [Parameters](parameters.md)) to interact with the dashboard
+1. The **page header** that contains the page title and the theme toggle switch button
+1. The **component container** where you can add your [components](components.md) to visualize your data
To create and add a page to your dashboard, do the following steps:
1. Set a `title` for your [`Page`][vizro.models.Page]
-2. Configure your `components`, see our guide on the [various options](components.md)
-3. (optional) Configure your `controls` , see our guides on [Filters](filters.md) and [Parameters](parameters.md)
-4. (optional) Configure your `layout` , see our guide on [Layouts](layouts.md)
-5. (optional) Give a `description` of your `Page` to the app's [meta tags](https://metatags.io/)
+1. Configure your `components`, see our guide on the [various options](components.md)
+1. (optional) Configure your `controls` , see our guides on [Filters](filters.md) and [Parameters](parameters.md)
+1. (optional) Configure your `layout` , see our guide on [Layouts](layouts.md)
+1. (optional) Give a `description` of your `Page` to the app's [meta tags](https://metatags.io/)
!!! example "Page"
=== "app.py"
@@ -51,51 +50,47 @@ To create and add a page to your dashboard, do the following steps:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: sunburst
- path: ['continent', 'country']
- values: pop
- color: lifeExp
- data_frame: gapminder
- id: sunburst
- type: graph
- controls:
- - column: continent
- targets:
- - sunburst
- type: filter
- - selector:
- options: ['lifeExp', 'pop']
- title: Color
- type: radio_items
- targets:
- - sunburst.color
- type: parameter
- title: Page Title
- description: "Longer description of the page content"
+ - components:
+ - figure:
+ _target_: sunburst
+ path: [continent, country]
+ values: pop
+ color: lifeExp
+ data_frame: gapminder
+ id: sunburst
+ type: graph
+ controls:
+ - column: continent
+ targets: [sunburst]
+ type: filter
+ - selector:
+ options: [lifeExp, pop]
+ title: Color
+ type: radio_items
+ targets: [sunburst.color]
+ type: parameter
+ title: Page Title
+ description: Longer description of the page content
```
- === "Result"
- [![Page]][Page]
- [Page]: ../../assets/user_guides/pages/page_sunburst.png
+ === "Result"
+ [![Page]][page]
An accordion page selector is automatically added to your dashboard in the top-left of the control container for through the different pages. It will not be added if your dashboard consists of only one page.
You can additionally navigate through the different pages by going directly to the relevant page URL (more details in next section).
-
## Customize the page URL
-By default, the page URL is automatically generated based on the `id` of the page. For example, if `id="This is my first page"`
-the generated page URL will be `path=this-is-my-first-page`. You can then access the page via `localhost:/this-is-my-first-page`.
-Note that the page `id` defaults to be the same as the page `title` if not set.
-If you have multiple pages with the same `title` then you must assign a unique `id`.
+By default, the page URL is automatically generated based on the `id` of the page. For example, if `id="This is my first page"` the generated page URL will be `path=this-is-my-first-page`. You can then access the page via `localhost:/this-is-my-first-page`.
+
+Note that the page `id` defaults to be the same as the page `title` if not set. If you have multiple pages with the same `title` then you must assign a unique `id`.
The first page always has the URL prefix `/` assigned. A custom URL can, therefore, not be created for the first page.
@@ -137,39 +132,40 @@ To customize the page URL, pass a valid URL name to the `path` argument of [`Pag
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- Commodi repudiandae consequuntur voluptatum.
- type: card
- title: Page 1
- - components:
- - figure:
- _target_: sunburst
- path: ['continent', 'country']
- values: pop
- color: lifeExp
- data_frame: gapminder
- id: sunburst
- type: graph
- controls:
- - column: continent
- targets:
- - sunburst
- type: filter
- - selector:
- options: ['lifeExp', 'pop']
- title: Color
- type: radio_items
- targets:
- - sunburst.color
- type: parameter
- title: Page 2
- path: my-custom-url
+ - components:
+ - text: |
+ Commodi repudiandae consequuntur voluptatum.
+ type: card
+ title: Page 1
+ - components:
+ - figure:
+ _target_: sunburst
+ path: [continent, country]
+ values: pop
+ color: lifeExp
+ data_frame: gapminder
+ id: sunburst
+ type: graph
+ controls:
+ - column: continent
+ targets: [sunburst]
+ type: filter
+ - selector:
+ options: [lifeExp, pop]
+ title: Color
+ type: radio_items
+ targets: [sunburst.color]
+ type: parameter
+ title: Page 2
+ path: my-custom-url
```
You can now access the first page via `localhost:/` and the second page via `localhost:/my-custom-url`.
+
+[page]: ../../assets/user_guides/pages/page_sunburst.png
diff --git a/vizro-core/docs/pages/user-guides/parameters.md b/vizro-core/docs/pages/user-guides/parameters.md
index bb39a7a0c..c82707d4a 100644
--- a/vizro-core/docs/pages/user-guides/parameters.md
+++ b/vizro-core/docs/pages/user-guides/parameters.md
@@ -9,8 +9,8 @@ The [`Page`][vizro.models.Page] model accepts the `controls` argument, where you
To add a parameter to your page, do the following:
1. add the [`Parameter`][vizro.models.Parameter] model into the `controls` argument of the [`Page`][vizro.models.Page] model.
-2. add the `targets` argument
-3. add a selector model to the `selector` argument.
+1. add the `targets` argument
+1. add a selector model to the `selector` argument.
In the `targets` argument, you can specify the component and function argument that the parameter should be applied to in the form of `.` (for example, `scatter_chart.title`).
@@ -48,6 +48,7 @@ Unlike for the [`Filter`][vizro.models.Filter] model, you also have to configure
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -64,18 +65,17 @@ Unlike for the [`Filter`][vizro.models.Filter] model, you also have to configure
type: graph
controls:
- selector:
- options: ["My scatter chart", "A better title!", "Another title..."]
- multi: False
+ options: [My scatter chart, A better title!, Another title...]
+ multi: false
type: dropdown
targets:
- scatter_chart.title
type: parameter
title: My first page
```
- === "Result"
- [![Parameter]][Parameter]
- [Parameter]: ../../assets/user_guides/control/control4.png
+ === "Result"
+ [![Parameter]][parameter]
If you would like to pass `None` as a parameter and make a parameter optional, you can specify the string `"NONE"` in the `options` or `value` field.
@@ -133,6 +133,7 @@ If you want to change nested parameters, you can specify the `targets` argument
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -146,7 +147,7 @@ If you want to change nested parameters, you can specify the `targets` argument
y: sepal_length
size: petal_length
color: species
- color_discrete_map: {"setosa": "#00b4ff", "versicolor": "#ff9222"}
+ color_discrete_map: {setosa: '#00b4ff', versicolor: '#ff9222'}
id: scatter_chart
type: graph
- figure:
@@ -155,23 +156,22 @@ If you want to change nested parameters, you can specify the `targets` argument
x: sepal_width
y: sepal_length
color: species
- color_discrete_map: {"setosa": "#00b4ff", "versicolor": "#ff9222"}
+ color_discrete_map: {setosa: '#00b4ff', versicolor: '#ff9222'}
id: bar_chart
type: graph
controls:
- selector:
- options: ["#ff5267", "#3949ab"]
+ options: ['#ff5267', '#3949ab']
value: #3949ab
- multi: False
+ multi: false
type: dropdown
- targets: ["scatter_chart.color_discrete_map.virginica", "bar_chart.color_discrete_map.virginica"]
+ targets: [scatter_chart.color_discrete_map.virginica, bar_chart.color_discrete_map.virginica]
type: parameter
title: My first page
```
- === "Result"
- [![Nested]][Nested]
- [Nested]: ../../assets/user_guides/control/control5.png
+ === "Result"
+ [![Nested]][nested]
In the above example, the object passed to the function argument `color_discrete_map` is a dictionary which maps the different flower species to fixed colors (for example, `{"virginica":"blue"}`). In this case, only the value `blue` should be changed instead of the entire dictionary. This can be achieved by specifying a target as `scatter.color_discrete_map.virginica`.
@@ -180,3 +180,6 @@ Note that in the above example, one parameter affects multiple targets.
## Dynamic data parameters
If you use [dynamic data](data.md/#dynamic-data) that can be updated while the dashboard is running then you can pass parameters to the dynamic data function to alter the data loaded into your dashboard. For detailed instructions, refer to the section on [parametrized data loading](data.md/#parametrize-data-loading).
+
+[nested]: ../../assets/user_guides/control/control5.png
+[parameter]: ../../assets/user_guides/control/control4.png
diff --git a/vizro-core/docs/pages/user-guides/run.md b/vizro-core/docs/pages/user-guides/run.md
index df52e8c14..028eb5027 100644
--- a/vizro-core/docs/pages/user-guides/run.md
+++ b/vizro-core/docs/pages/user-guides/run.md
@@ -15,7 +15,6 @@ Most of our examples have a link below the code, [Run and edit this code in PyCa
You can use [PyCafe](https://py.cafe/snippet/vizro/v1) snippet mode to experiment with your own Vizro dashboards by dropping code into a new project.
-
## Default built-in Flask development server
!!! example "Default built-in Flask development server"
@@ -38,9 +37,10 @@ You can use [PyCafe](https://py.cafe/snippet/vizro/v1) snippet mode to experimen
Vizro().build(dashboard).run()
```
+
1. create a Python file named `app.py`.
-2. type the command `python app.py` into your terminal.
-3. information below will be displayed in your terminal, go to [http://127.0.0.1:8050/](http://127.0.0.1:8050/).
+1. type the command `python app.py` into your terminal.
+1. information below will be displayed in your terminal, go to [http://127.0.0.1:8050/](http://127.0.0.1:8050/).
```
Dash is running on http://127.0.0.1:8050/
@@ -51,8 +51,7 @@ INFO:werkzeug:WARNING: This is a development server. Do not use it in a producti
```
!!! warning "In production"
-
- As per the above warning message, which is [further explained in the Flask documentation](https://flask.palletsprojects.com/en/3.0.x/deploying/), the Flask development server is intended for use only during local development and **should not** be used when deploying to production. Instead, you should instead use a production-ready solution such as [Gunicorn](#gunicorn).
+ The above warning message is [further explained in the Flask documentation](https://flask.palletsprojects.com/en/3.0.x/deploying/). The Flask development server is intended for use only during local development and **should not** be used when deploying to production. Instead, you should instead use a production-ready solution such as [Gunicorn](#gunicorn).
### Automatic reloading and debugging
@@ -64,11 +63,11 @@ Setting `debug=True` enables [Dash Dev Tools](https://dash.plotly.com/devtools).
In addition, some errors generated at run time can also be viewed via the browser console (for example in `Chrome` see `View > Developer > Developer Tools > Console`).
-
## Jupyter
+
The dashboard application can be launched in a Jupyter environment in `inline`, `external`, and `jupyterlab` mode.
-!!! example "Run in a Jupyter Notebook in inline mode"
+!!! example "Run in a Jupyter Notebook in inline mode"
=== "app.ipynb"
```py linenums="1"
from vizro import Vizro
@@ -87,16 +86,16 @@ The dashboard application can be launched in a Jupyter environment in `inline`,
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run(jupyter_mode="external")
```
+
- by default, the mode is set to `inline` in `run()` and the dashboard will be displayed inside your Jupyter environment.
- you can specify `jupyter_mode="external"` and a link will be displayed to direct you to the localhost where the dashboard is running.
- you can use tab mode by `jupyter_mode="tab"` to automatically open the app in a new browser
!!! note "Reloading and debugging"
-
Code reloading and hot reloading do not work within a Jupyter Notebook. Instead, there are two methods to reload the dashboard:
- * Restart the Jupyter kernel and re-run your notebook.
- * Add a cell containing `from vizro import Vizro; Vizro._reset()` to the top of your notebook and re-run it. With this method, there is no need to restart the Jupyter kernel.
+ - Restart the Jupyter kernel and re-run your notebook.
+ - Add a cell containing `from vizro import Vizro; Vizro._reset()` to the top of your notebook and re-run it. With this method, there is no need to restart the Jupyter kernel.
## Gunicorn
@@ -126,17 +125,18 @@ The dashboard application can be launched in a Jupyter environment in `inline`,
```
1. The Vizro `app` object is a WSGI application that exposes the underlying Flask app; this will be used by Gunicorn.
- 2. Enable the same app to still be run using the built-in Flask server with `python app.py` for development purposes.
+ 1. Enable the same app to still be run using the built-in Flask server with `python app.py` for development purposes.
To run using Gunicorn with four worker processes, execute
+
```bash
gunicorn app:app --workers 4
```
+
in the command line. For more Gunicorn configuration options, refer to [Gunicorn documentation](https://docs.gunicorn.org/).
!!! warning "In production"
-
- If your dashboard uses [dynamic data](data.md#dynamic-data) that can be refreshed while the dashboard is running then you should [configure your data manager cache](data.md#configure-cache) to use a backend that supports multiple processes.
+ If your dashboard uses [dynamic data](data.md#dynamic-data) that can be refreshed while the dashboard is running then you should [configure your data manager cache](data.md#configure-cache) to use a back end that supports multiple processes.
## Deployment
@@ -149,6 +149,6 @@ Internally, `app = Vizro()` contains a Flask app in `app.dash.server`. However,
[`Vizro`][vizro.Vizro] accepts `**kwargs` that are passed through to `Dash`. This enables you to configure the underlying Dash app using the same [arguments that are available](https://dash.plotly.com/reference#dash.dash) in `Dash`. For example, in a deployment context, these arguments may be useful:
-- `url_base_pathname`: serve your Vizro app at a specific path rather than at the domain root. For example, if you host your dashboard at http://www.example.com/my_dashboard/ then you would set `url_base_pathname="/my_dashboard/"` or an environment variable `DASH_URL_BASE_PATHNAME="/my_dashboard/"`.
+- `url_base_pathname`: serve your Vizro app at a specific path rather than at the domain root. For example, if you host your dashboard at `http://www.example.com/my_dashboard/` then you would set `url_base_pathname="/my_dashboard/"` or an environment variable `DASH_URL_BASE_PATHNAME="/my_dashboard/"`.
- `serve_locally`: set to `False` to [serve Dash component libraries from a Content Delivery Network (CDN)](https://dash.plotly.com/external-resources#serving-dash's-component-libraries-locally-or-from-a-cdn), which reduces load on the server and can improve performance. Vizro uses [jsDeliver](https://www.jsdelivr.com/) as a CDN for CSS and JavaScript sources.
- `assets_external_path`: when `serve_locally=False`, you can also set `assets_external_path` or an environment variable `DASH_ASSETS_EXTERNAL_PATH` to [serve your own assets from a CDN](https://dash.plotly.com/external-resources#load-assets-from-a-folder-hosted-on-a-cdn).
diff --git a/vizro-core/docs/pages/user-guides/selectors.md b/vizro-core/docs/pages/user-guides/selectors.md
index 10481d2ba..a1bd4be20 100644
--- a/vizro-core/docs/pages/user-guides/selectors.md
+++ b/vizro-core/docs/pages/user-guides/selectors.md
@@ -6,10 +6,7 @@ The [`Filter`][vizro.models.Filter] or the [`Parameter`][vizro.models.Parameter]
## Categorical selectors
-Within the categorical selectors, a clear distinction exists between multi-option and single-option selectors.
-For instance, the [`Checklist`][vizro.models.Checklist] functions as a multi-option selector by default while
-the [`RadioItem`][vizro.models.RadioItems] serves as a single-option selector by default. However, the
-[`Dropdown`][vizro.models.Dropdown] can function as both a multi-option or single-option selector.
+Within the categorical selectors, a clear distinction exists between multi-option and single-option selectors. For instance, the [`Checklist`][vizro.models.Checklist] functions as a multi-option selector by default while the [`RadioItem`][vizro.models.RadioItems] serves as a single-option selector by default. However, the [`Dropdown`][vizro.models.Dropdown] can function as both a multi-option or single-option selector.
For more information, refer to the API reference of the selector, or the documentation of its underlying Dash component:
@@ -18,15 +15,12 @@ For more information, refer to the API reference of the selector, or the documen
- [`RadioItems`][vizro.models.RadioItems] based on [`dcc.RadioItems`](https://dash.plotly.com/dash-core-components/radioitems)
!!! note
-
- When configuring the `options` of the categorical selectors, you can either provide:
+ When configuring the `options` of the categorical selectors, you can either give:
- a list of values `options = ['Value A', 'Value B', 'Value C']`
- or a dictionary of label-value mappings `options=[{'label': 'True', 'value': True}, {'label': 'False', 'value': False}]`
- The later is required if you want to provide different display labels to your option values or in case you want to
- provide boolean values as options. In this case, you need to provide a string label for your boolean values as
- boolean values cannot be displayed properly as labels in the underlying Dash components.
+ The later is required if you want to provide different display labels to your option values or in case you want to provide boolean values as options. In this case, you need to provide a string label for your boolean values as boolean values cannot be displayed properly as labels in the underlying Dash components.
## Numerical selectors
@@ -36,11 +30,7 @@ For more information, refer to the API reference of the selector, or the documen
- [`RangeSlider`][vizro.models.RangeSlider] based on [`dcc.RangeSlider`](https://dash.plotly.com/dash-core-components/rangeslider)
!!! note
-
- When configuring the [`Slider`][vizro.models.Slider] and the [`RangeSlider`][vizro.models.RangeSlider] with float values, and using `step` with an integer value, you may notice
- unexpected behavior, such as the drag value being outside its indicated marks.
- To our knowledge, this is a current bug in the underlying [`dcc.Slider`](https://dash.plotly.com/dash-core-components/slider) and
- [`dcc.RangeSlider`](https://dash.plotly.com/dash-core-components/rangeslider) component, which you can circumvent by adapting the `step` size accordingly.
+ When configuring the [`Slider`][vizro.models.Slider] and the [`RangeSlider`][vizro.models.RangeSlider] with float values, and using `step` with an integer value, you may notice unexpected behavior, such as the drag value being outside its indicated marks. To our knowledge, this is a current bug in the underlying [`dcc.Slider`](https://dash.plotly.com/dash-core-components/slider) and [`dcc.RangeSlider`](https://dash.plotly.com/dash-core-components/rangeslider) component, which you can circumvent by adapting the `step` size as needed.
## Temporal selectors
@@ -49,7 +39,6 @@ For more information, refer to the API reference of the selector, or the documen
- [`DatePicker`][vizro.models.DatePicker] based on [`dmc.DateRangePicker`](https://www.dash-mantine-components.com/components/datepicker#daterangepicker) and [`dmc.DatePicker`](https://www.dash-mantine-components.com/components/datepicker)
!!! note
-
When the [`DatePicker`][vizro.models.DatePicker] is configured with `range=True` (the default), the underlying component is `dmc.DateRangePicker`. When `range=False` the underlying component is `dmc.DatePicker`.
When configuring the [`DatePicker`][vizro.models.DatePicker] make sure to provide your dates for `min`, `max` and `value` arguments in `"yyyy-mm-dd"` format or as `datetime` type (for example, `datetime.datetime(2024, 01, 01)`).
diff --git a/vizro-core/docs/pages/user-guides/table.md b/vizro-core/docs/pages/user-guides/table.md
index 19197c465..80e8e53dc 100755
--- a/vizro-core/docs/pages/user-guides/table.md
+++ b/vizro-core/docs/pages/user-guides/table.md
@@ -2,46 +2,32 @@
This guide shows you how to visualize tables in Vizro.
-There are two ways to visualize tables in Vizro, using either [AG Grid](#ag-grid) or [Dash DataTable](#dash-datatable).
-In general, [AG Grid](#ag-grid) is Vizro's recommended table implementation, but sometimes it may make sense to use the [Dash DataTable](#dash-datatable) instead.
+There are two ways to visualize tables in Vizro, using either [AG Grid](#ag-grid) or [Dash DataTable](#dash-datatable). In general, [AG Grid](#ag-grid) is Vizro's recommended table implementation, but sometimes it may make sense to use the [Dash DataTable](#dash-datatable) instead.
## Choose between AG Grid and Dash DataTable
-Vizro offers two models - the [`AgGrid`][vizro.models.AgGrid] model and the [`Table`][vizro.models.Table] model - for the above two approaches respectively.
-They both visualize tabular data in similar ways.
+Vizro offers two models - the [`AgGrid`][vizro.models.AgGrid] model and the [`Table`][vizro.models.Table] model - for the above two approaches respectively. They both visualize tabular data in similar ways.
-The main difference between the two is that the [`AgGrid`][vizro.models.AgGrid] model is based on Plotly's [Dash AG Grid](https://dash.plotly.com/dash-ag-grid) component,
-while the [`Table`][vizro.models.Table] model is based on the [Dash DataTable](https://dash.plotly.com/datatable) component.
-
-Both approaches have similar base features, and are configurable in similar ways. However, the AG Grid offers more advanced features out-of-the-box, is more customizable
-and also ships a powerful enterprise version. This is why it is Vizro's recommended table implementation. At the same time, the Dash DataTable can be used if developers are
-already familiar with it, or if some custom functionality is easier to implement using the Dash DataTable.
+The main difference between the two is that the [`AgGrid`][vizro.models.AgGrid] model is based on Plotly's [Dash AG Grid](https://dash.plotly.com/dash-ag-grid) component, while the [`Table`][vizro.models.Table] model is based on the [Dash DataTable](https://dash.plotly.com/datatable) component.
+Both approaches have similar base features, and are configurable in similar ways. However, the AG Grid offers more advanced features out-of-the-box, is more customizable and also ships a powerful enterprise version. This is why it is Vizro's recommended table implementation. At the same time, the Dash DataTable can be used if developers are already familiar with it, or if some custom functionality is easier to implement using the Dash DataTable.
## AG Grid
-[AG Grid](https://www.ag-grid.com/) is an interactive table/grid component designed for viewing, editing, and exploring large datasets. It
-is Vizro's recommended table implementation.
+[AG Grid](https://www.ag-grid.com/) is an interactive table/grid component designed for viewing, editing, and exploring large datasets. It is Vizro's recommended table implementation.
-The Vizro [`AgGrid`][vizro.models.AgGrid] model is based on the [Dash AG Grid](https://dash.plotly.com/dash-ag-grid), which is in turn based the
-original [Javascript implementation](https://www.ag-grid.com/).
+The Vizro [`AgGrid`][vizro.models.AgGrid] model is based on the [Dash AG Grid](https://dash.plotly.com/dash-ag-grid), which is in turn based the original [Javascript implementation](https://www.ag-grid.com/).
### Basic usage
To add a [`AgGrid`][vizro.models.AgGrid] to your page, do the following:
-1. Insert the [`AgGrid`][vizro.models.AgGrid] model into the `components` argument of the
-[`Page`][vizro.models.Page] model.
-2. Enter the `dash_ag_grid` function under the `figure` argument (imported via `from vizro.tables import dash_ag_grid`).
-
-The Vizro version of this AG Grid differs in one way from the original Dash AG Grid: it requires the user to pass a pandas DataFrame as the source of data.
-As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`. Most other [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments.
-Note that some defaults are set for some arguments (for example, for `columnDefs`) to help with styling and usability.
-Sometimes a parameter may not work because it requires a callback to function. In that case you can try [creating a custom AG Grid callable](custom-tables.md).
+1. Insert the [`AgGrid`][vizro.models.AgGrid] model into the `components` argument of the [`Page`][vizro.models.Page] model.
+1. Enter the `dash_ag_grid` function under the `figure` argument (imported via `from vizro.tables import dash_ag_grid`).
+The Vizro version of this AG Grid differs in one way from the original Dash AG Grid: it requires the user to pass a pandas DataFrame as the source of data. As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`. Most other [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments. Note that some defaults are set for some arguments (for example, for `columnDefs`) to help with styling and usability. Sometimes a parameter may not work because it requires a callback to function. In that case you can try [creating a custom AG Grid callable](custom-tables.md).
!!! example "Basic Dash AG Grid"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -59,29 +45,28 @@ Sometimes a parameter may not work because it requires a callback to function. I
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - figure:
- _target_: dash_ag_grid
- data_frame: gapminder
- type: ag_grid
- title: Default Dash AG Grid
+ - components:
+ - figure:
+ _target_: dash_ag_grid
+ data_frame: gapminder
+ type: ag_grid
+ title: Default Dash AG Grid
```
- === "Result"
- [![AGGrid]][AGGrid]
- [AGGrid]: ../../assets/user_guides/table/aggrid.png
+ === "Result"
+ [![AGGrid]][aggrid]
### Enable pagination
-Pagination is a visual alternative to using vertical scroll. It can also improve loading time if you have many rows.
-You can turn it on by setting `dashGridOptions={"pagination": True}`.
-!!! example "Basic Dash AG Grid"
+Pagination is a visual alternative to using vertical scroll. It can also improve loading time if you have many rows. You can turn it on by setting `dashGridOptions={"pagination": True}`.
+!!! example "Basic Dash AG Grid"
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -99,37 +84,34 @@ You can turn it on by setting `dashGridOptions={"pagination": True}`.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - figure:
- _target_: dash_ag_grid
- data_frame: gapminder
- dashGridOptions:
- pagination: true
- type: ag_grid
- title: Dash AG Grid with pagination
+ - components:
+ - figure:
+ _target_: dash_ag_grid
+ data_frame: gapminder
+ dashGridOptions:
+ pagination: true
+ type: ag_grid
+ title: Dash AG Grid with pagination
```
- === "Result"
- [![AGGrid]][AGGrid]
- [AGGrid]: ../../assets/user_guides/table/aggrid-pagination.png
+ === "Result"
+ [![AGGrid]][aggrid]
### Formatting columns
#### Numbers
-One of the most common tasks when working with tables is to format the columns so that displayed numbers are more readable.
-To do this, you can use the native functionality of [value formatters](https://dash.plotly.com/dash-ag-grid/value-formatters)
-or the Vizro pre-defined [custom cell data types](https://dash.plotly.com/dash-ag-grid/cell-data-types#providing-custom-cell-data-types) as shown below.
+One of the most common tasks when working with tables is to format the columns so that displayed numbers are more readable. To do this, you can use the native functionality of [value formatters](https://dash.plotly.com/dash-ag-grid/value-formatters) or the Vizro pre-defined [custom cell data types](https://dash.plotly.com/dash-ag-grid/cell-data-types#providing-custom-cell-data-types) as shown below.
The available custom cell types for Vizro are `dollar`, `euro`, `percent` and `numeric`.
-To use these, define your desired `` alongside the chosen `cellDataType` in
-the `columnDefs` argument of your `dash_ag_grid` function:
+To use these, define your desired `` alongside the chosen `cellDataType` in the `columnDefs` argument of your `dash_ag_grid` function:
```py
columnDefs = [{"field": "", "cellDataType": "euro"}]
@@ -138,7 +120,6 @@ columnDefs = [{"field": "", "cellDataType": "euro"}]
In the example below we select and format some columns of the gapminder data.
!!! example "AG Grid with formatted columns"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -168,6 +149,7 @@ In the example below we select and format some columns of the gapminder data.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -190,33 +172,23 @@ In the example below we select and format some columns of the gapminder data.
type: ag_grid
title: Example of AG Grid with formatted columns
```
- === "Result"
- [![AGGrid2]][AGGrid2]
- [AGGrid2]: ../../assets/user_guides/table/formatted_aggrid.png
+ === "Result"
+ [![AGGrid2]][aggrid2]
#### Dates
-For the [`AgGrid`][vizro.models.AgGrid] model to sort and filter dates correctly, the date must either be of
-string format `yyyy-mm-dd` (see [Dash AG Grid docs](https://dash.plotly.com/dash-ag-grid/date-filters#example:-date-filter))
-or a pandas datetime object. Any pandas datetime column will be transformed into the `yyyy-mm-dd` format automatically.
+For the [`AgGrid`][vizro.models.AgGrid] model to sort and filter dates correctly, the date must either be of string format `yyyy-mm-dd` (see [Dash AG Grid docs](https://dash.plotly.com/dash-ag-grid/date-filters#example:-date-filter)) or a pandas datetime object. Any pandas datetime column will be transformed into the `yyyy-mm-dd` format automatically.
#### Objects and strings
-No specific formatting is available for custom objects and strings, however you can make use of [Value Formatters](https://dash.plotly.com/dash-ag-grid/value-formatters)
-to format displayed strings automatically.
-
+No specific formatting is available for custom objects and strings, however you can make use of [Value Formatters](https://dash.plotly.com/dash-ag-grid/value-formatters) to format displayed strings automatically.
### Styling and changing the AG Grid
-As mentioned above, all [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments. Below you can find
-an example of a styled AG Grid where some conditional formatting is applied, and where the columns are editable, but
-not filterable or resizable. There are more ways to alter the grid beyond this showcase. AG Grid, like any other Vizro
-component, can be customized using custom CSS. You can find information in
-the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-selected-components).
+As mentioned above, all [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments. Below you can find an example of a styled AG Grid where some conditional formatting is applied, and where the columns are editable, but not filterable or resizable. There are more ways to alter the grid beyond this showcase. AG Grid, like any other Vizro component, can be customized using custom CSS. You can find information in the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-selected-components).
!!! example "Styled and modified Dash AG Grid"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -284,6 +256,7 @@ the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-select
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -299,28 +272,28 @@ the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-select
- field: year
- field: lifeExp
valueFormatter:
- function: "d3.format('.1f')(params.value)"
+ function: d3.format('.1f')(params.value)
- field: gdpPercap
valueFormatter:
- function: "d3.format('$,.1f')(params.value)"
+ function: d3.format('$,.1f')(params.value)
cellStyle:
styleConditions:
- condition: params.value < 1045
style:
- backgroundColor: "#ff9222"
+ backgroundColor: '#ff9222'
- condition: params.value >= 1045 && params.value <= 4095
style:
- backgroundColor: "#de9e75"
+ backgroundColor: '#de9e75'
- condition: params.value > 4095 && params.value <= 12695
style:
- backgroundColor: "#aaa9ba"
+ backgroundColor: '#aaa9ba'
- condition: params.value > 12695
style:
- backgroundColor: "#00b4ff"
+ backgroundColor: '#00b4ff'
- field: pop
type: rightAligned
valueFormatter:
- function: "d3.format(',.0f')(params.value)"
+ function: d3.format(',.0f')(params.value)
defaultColDef:
resizable: false
filter: false
@@ -329,10 +302,9 @@ the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-select
type: ag_grid
title: Example of a Dash AG Grid
```
- === "Result"
- [![AGGrid3]][AGGrid3]
- [AGGrid3]: ../../assets/user_guides/table/styled_aggrid.png
+ === "Result"
+ [![AGGrid3]][aggrid3]
If the available arguments are not sufficient, there is always the option to [create a custom AG Grid callable](custom-tables.md).
@@ -348,19 +320,14 @@ The Vizro [`Table`][vizro.models.Table] model is based on the [Dash DataTable](h
To add a [`Table`][vizro.models.Table] to your page, do the following:
-1. Insert the [`Table`][vizro.models.Table] model into the `components` argument of the
-[`Page`][vizro.models.Page] model.
-2. Enter the `dash_data_table` function under the `figure` argument (imported via `from vizro.tables import dash_data_table`).
-
+1. Insert the [`Table`][vizro.models.Table] model into the `components` argument of the [`Page`][vizro.models.Page] model.
+1. Enter the `dash_data_table` function under the `figure` argument (imported via `from vizro.tables import dash_data_table`).
-The Vizro version of this table differs in one way from the original table: it requires the user to pass a pandas DataFrame as the source of data.
-As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`.
+The Vizro version of this table differs in one way from the original table: it requires the user to pass a pandas DataFrame as the source of data. As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`.
-All other [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Note that we are
-setting some defaults for some arguments to help with styling.
+All other [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Note that we are setting some defaults for some arguments to help with styling.
!!! example "Dash DataTable"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -380,31 +347,29 @@ setting some defaults for some arguments to help with styling.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: dash_data_table
- data_frame: gapminder_2007
- title: Dash DataTable
- type: table
- title: Example of a Dash DataTable
+ - components:
+ - figure:
+ _target_: dash_data_table
+ data_frame: gapminder_2007
+ title: Dash DataTable
+ type: table
+ title: Example of a Dash DataTable
```
- === "Result"
- [![Table]][Table]
- [Table]: ../../assets/user_guides/table/table.png
+ === "Result"
+ [![Table]][table]
### Styling and changing the Dash DataTable
-As mentioned above, all [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Below you can find
-an example of a styled table where some conditional formatting is applied. There are many more ways to alter the table beyond this showcase.
+As mentioned above, all [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Below you can find an example of a styled table where some conditional formatting is applied. There are many more ways to alter the table beyond this showcase.
!!! example "Styled Dash DataTable"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -467,6 +432,7 @@ an example of a styled table where some conditional formatting is applied. There
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -504,12 +470,12 @@ an example of a styled table where some conditional formatting is applied. There
backgroundColor: dodgerblue
color: white
- if:
- filter_query: "{lifeExp} < 55"
+ filter_query: '{lifeExp} < 55'
column_id: lifeExp
- backgroundColor: "#85144b"
+ backgroundColor: '#85144b'
color: white
- if:
- filter_query: "{gdpPercap} > 10000"
+ filter_query: '{gdpPercap} > 10000'
column_id: gdpPercap
backgroundColor: green
color: white
@@ -524,26 +490,20 @@ an example of a styled table where some conditional formatting is applied. There
title: Dash DataTable
```
- === "Result"
- [![Table2]][Table2]
- [Table2]: ../../assets/user_guides/table/styled_table.png
+ === "Result"
+ [![Table2]][table2]
If the available arguments are not sufficient, there is always the option to create a [custom Dash DataTable](custom-tables.md).
-
## Add title, header, and footer
-The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] models accept a `title`, `header` and
-`footer` argument. This is useful for providing context to the data being displayed, or for adding a description of
-the data.
+The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] models accept a `title`, `header` and `footer` argument. This is useful for providing context to the data being displayed, or for adding a description of the data.
- **title**: Displayed as an [H3 header](https://dash.plotly.com/dash-html-components/h3), useful for summarizing the main topic or insight of the component.
- **header**: Accepts markdown text, ideal for extra descriptions, subtitles, or detailed data insights.
- **footer**: Accepts markdown text, commonly used for citing data sources, providing information on the last update, or adding disclaimers.
-
-
### Formatted AgGrid
!!! example "Formatted AgGrid"
@@ -571,30 +531,29 @@ the data.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: dash_ag_grid
- data_frame: gapminder_2007
- dashGridOptions:
- pagination: true
- title: Gapminder Data Insights
- header: |
- #### An Interactive Exploration of Global Health, Wealth, and Population
- footer: |
- SOURCE: **Plotly gapminder data set, 2024**
- type: ag_grid
- title: Formatted AgGrid
+ - components:
+ - figure:
+ _target_: dash_ag_grid
+ data_frame: gapminder_2007
+ dashGridOptions:
+ pagination: true
+ title: Gapminder Data Insights
+ header: |
+ #### An Interactive Exploration of Global Health, Wealth, and Population
+ footer: |
+ SOURCE: **Plotly gapminder data set, 2024**
+ type: ag_grid
+ title: Formatted AgGrid
```
- === "Result"
- [![FormattedGrid]][FormattedGrid]
-
- [FormattedGrid]: ../../assets/user_guides/components/formatted_aggrid.png
+ === "Result"
+ [![FormattedGrid]][formattedgrid]
### Formatted DataTable
@@ -623,24 +582,32 @@ the data.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: dash_data_table
- data_frame: gapminder_2007
- title: Gapminder Data Insights
- header: |
- #### An Interactive Exploration of Global Health, Wealth, and Population
- footer: |
- SOURCE: **Plotly gapminder data set, 2024**
- type: table
- title: Formatted DataTable
+ - components:
+ - figure:
+ _target_: dash_data_table
+ data_frame: gapminder_2007
+ title: Gapminder Data Insights
+ header: |
+ #### An Interactive Exploration of Global Health, Wealth, and Population
+ footer: |
+ SOURCE: **Plotly gapminder data set, 2024**
+ type: table
+ title: Formatted DataTable
```
- === "Result"
- [![FormattedTable]][FormattedTable]
- [FormattedTable]: ../../assets/user_guides/components/formatted_table.png
+ === "Result"
+ [![FormattedTable]][formattedtable]
+
+[aggrid]: ../../assets/user_guides/table/aggrid.png
+[aggrid2]: ../../assets/user_guides/table/formatted_aggrid.png
+[aggrid3]: ../../assets/user_guides/table/styled_aggrid.png
+[formattedgrid]: ../../assets/user_guides/components/formatted_aggrid.png
+[formattedtable]: ../../assets/user_guides/components/formatted_table.png
+[table]: ../../assets/user_guides/table/table.png
+[table2]: ../../assets/user_guides/table/styled_table.png
diff --git a/vizro-core/docs/pages/user-guides/tabs.md b/vizro-core/docs/pages/user-guides/tabs.md
index 09154177e..1811d0cac 100755
--- a/vizro-core/docs/pages/user-guides/tabs.md
+++ b/vizro-core/docs/pages/user-guides/tabs.md
@@ -1,8 +1,6 @@
# How to use tabs
-[`Tabs`][vizro.models.Tabs] organize and separate groups of related content in a dashboard, letting users switch between different sections or views.
-They are essentially a way of putting multiple [`Containers`][vizro.models.Container] in the same screen space, and letting the user switch between them.
-`Containers` enable the grouping of page components into sections and subsections. See our [user guide on `Containers`](container.md) for more information.
+[`Tabs`][vizro.models.Tabs] organize and separate groups of related content in a dashboard, letting users switch between different sections or views. They are essentially a way of putting multiple [`Containers`][vizro.models.Container] in the same screen space, and letting the user switch between them. `Containers` enable the grouping of page components into sections and subsections. See our [user guide on `Containers`](container.md) for more information.
{ width="400"}
@@ -16,14 +14,12 @@ This guide shows you how to use tabs to organize your `Containers` into subsecti
By using [`Tabs`][vizro.models.Tabs], the following applies:
- [`Filters`][vizro.models.Filter] affect all components on all tabs (opened and closed) of the page if not specified otherwise inside `Filter.targets`
-- The `title` of the [`Container`][vizro.models.Container] inserted into `Tabs.tabs` will be displayed as a tab label, and the title will be removed from the `Container`
-
+- The `title` of the [`Container`][vizro.models.Container] inserted into `Tabs.tabs` will be displayed as a tab label, and the title will be removed from the `Container`
To add [`Tabs`][vizro.models.Tabs] to your page, do the following:
1. Insert the [`Tabs`][vizro.models.Tabs] into the `components` argument of the [`Page`][vizro.models.Page]
-2. Insert your [`Containers`][vizro.models.Container] into the `tabs` argument of the [`Tabs`][vizro.models.Tabs]
-
+1. Insert your [`Containers`][vizro.models.Container] into the `tabs` argument of the [`Tabs`][vizro.models.Tabs]
!!! example "Tabs"
=== "app.py"
@@ -88,52 +84,53 @@ To add [`Tabs`][vizro.models.Tabs] to your page, do the following:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - tabs:
- - title: Tab I
- type: container
- components:
- - type: graph
- figure:
- _target_: bar
- data_frame: gapminder_2007
- title: Graph 1
- x: continent
- y: lifeExp
- color: continent
- - type: graph
- figure:
- _target_: box
- data_frame: gapminder_2007
- title: Graph 2
- x: continent
- y: lifeExp
- color: continent
- - title: Tab II
- type: container
- components:
- - type: graph
- figure:
- _target_: scatter
- data_frame: gapminder_2007
- title: Graph 3
- x: gdpPercap
- y: lifeExp
- size: pop
- color: continent
- type: tabs
+ components:
+ - type: tabs
+ tabs:
+ - title: Tab I
+ type: container
+ components:
+ - type: graph
+ figure:
+ _target_: bar
+ data_frame: gapminder_2007
+ title: Graph 1
+ x: continent
+ y: lifeExp
+ color: continent
+ - type: graph
+ figure:
+ _target_: box
+ data_frame: gapminder_2007
+ title: Graph 2
+ x: continent
+ y: lifeExp
+ color: continent
+ - title: Tab II
+ type: container
+ components:
+ - type: graph
+ figure:
+ _target_: scatter
+ data_frame: gapminder_2007
+ title: Graph 3
+ x: gdpPercap
+ y: lifeExp
+ size: pop
+ color: continent
controls:
- - type: filter
- column: continent
+ - type: filter
+ column: continent
title: Tabs
```
- === "Result"
- [![Tabs]][Tabs]
+ === "Result"
+ [![Tabs]][tabs]
- [Tabs]: ../../assets/user_guides/components/tabs.png
+[tabs]: ../../assets/user_guides/components/tabs.png
diff --git a/vizro-core/docs/pages/user-guides/themes.md b/vizro-core/docs/pages/user-guides/themes.md
index 6f78441d5..ac1d6fc7b 100644
--- a/vizro-core/docs/pages/user-guides/themes.md
+++ b/vizro-core/docs/pages/user-guides/themes.md
@@ -1,15 +1,13 @@
# How to use themes
-This guide shows you how to use themes. Themes are pre-designed collections of stylings that are applied to entire charts and dashboards.
-The themes provided by Vizro are infused with our design best practices that make charts and dashboards look visually consistent and professional.
+This guide shows you how to use themes. Themes are pre-designed collections of stylings that are applied to entire charts and dashboards. The themes provided by Vizro are infused with our design best practices that make charts and dashboards look visually consistent and professional.
## Themes in dashboards
-The [`Dashboard`][vizro.models.Dashboard] model accepts an optional `theme` argument, where you can choose between
-a `vizro_dark` and a `vizro_light` theme. If not specified then `theme` defaults to `vizro_dark`. The theme is applied to the entire dashboard and its charts/components when a user first loads your dashboard. Regardless of the theme applied on first load, users can always switch between light and dark themes via the toggle button in the upper-right corner of the dashboard.
+
+The [`Dashboard`][vizro.models.Dashboard] model accepts an optional `theme` argument, where you can choose between a `vizro_dark` and a `vizro_light` theme. If not specified then `theme` defaults to `vizro_dark`. The theme is applied to the entire dashboard and its charts/components when a user first loads your dashboard. Regardless of the theme applied on first load, users can always switch between light and dark themes via the toggle button in the upper-right corner of the dashboard.
!!! example "Change theme"
=== "app.py"
-
```{.python pycafe-link hl_lines="18"}
import vizro.models as vm
import vizro.plotly.express as px
@@ -32,47 +30,40 @@ a `vizro_dark` and a `vizro_light` theme. If not specified then `theme` defaults
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml hl_lines="12"
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: scatter_matrix
- color: species
- data_frame: iris
- dimensions: ["sepal_length", "sepal_width", "petal_length", "petal_width"]
- type: graph
- title: Changing themes
+ - components:
+ - figure:
+ _target_: scatter_matrix
+ color: species
+ data_frame: iris
+ dimensions: [sepal_length, sepal_width, petal_length, petal_width]
+ type: graph
+ title: Changing themes
theme: vizro_light
```
+
=== "Result - vizro_light"
- [![Light]][Light]
+ [![Light]][light]
- [Light]: ../../assets/user_guides/themes/light.png
=== "Result - vizro_dark"
- [![Dark]][Dark]
-
- [Dark]: ../../assets/user_guides/themes/dark.png
-
+ [![Dark]][dark]
## Themes in plotly charts
You can also use our templates for plotly charts outside the dashboard. This is useful in a few contexts:
-* Creation of standalone charts to be used independently of a Vizro dashboard.
-* Rapid development of charts for eventual use in a Vizro dashboard, for example in a Jupyter Notebook.
+- Creation of standalone charts to be used independently of a Vizro dashboard.
+- Rapid development of charts for eventual use in a Vizro dashboard, for example in a Jupyter Notebook.
!!! note
+ Using `import vizro.plotly.express as px` is equal to using `import plotly.express as px`, but with the added benefit of being able to integrate the resulting chart code into a Vizro dashboard. Vizro offers a minimal layer on top of Plotly's existing charting library, allowing you to seamlessly use all the existing charts and functionalities provided by plotly.express without any modifications.
- Using `import vizro.plotly.express as px` is equivalent to using `import plotly.express as px`,
- but with the added benefit of being able to integrate the resulting chart code into a Vizro dashboard.
- Vizro offers a minimal layer on top of Plotly's existing charting library, allowing you to seamlessly use all the
- existing charts and functionalities provided by plotly.express without any modifications.
-
-Our `vizro_dark` and `vizro_light` themes are automatically registered to `plotly.io.templates` when importing Vizro.
-Consult the plotly documentation for [more details on how templates work in plotly](https://plotly.com/python/templates/#theming-and-templates).
+Our `vizro_dark` and `vizro_light` themes are automatically registered to `plotly.io.templates` when importing Vizro. Consult the plotly documentation for [more details on how templates work in plotly](https://plotly.com/python/templates/#theming-and-templates).
By default, plots imported from `vizro.plotly.express` have the `vizro_dark` theme applied. This can be altered either globally or for individual plots.
@@ -87,14 +78,20 @@ pio.templates.default = "vizro_light"
```
### Set themes for selected charts
+
To change the template for a selected chart only, use the `template` parameter and run:
```python
import vizro.plotly.express as px
df = px.data.iris()
-px.scatter_matrix(df,
- dimensions=["sepal_length", "sepal_width", "petal_length", "petal_width"],
- color="species",
- template="vizro_light")
+px.scatter_matrix(
+ df,
+ dimensions=["sepal_length", "sepal_width", "petal_length", "petal_width"],
+ color="species",
+ template="vizro_light",
+)
```
+
+[dark]: ../../assets/user_guides/themes/dark.png
+[light]: ../../assets/user_guides/themes/light.png
diff --git a/vizro-core/docs/pages/user-guides/visual-formatting.md b/vizro-core/docs/pages/user-guides/visual-formatting.md
index 7b384f3e9..56d1d2d52 100644
--- a/vizro-core/docs/pages/user-guides/visual-formatting.md
+++ b/vizro-core/docs/pages/user-guides/visual-formatting.md
@@ -1,17 +1,13 @@
# How to customize the style of Vizro dashboards
-Vizro has a default styling to help users with no design experience get started.
-There are several options if you want to customize the style:
+Vizro has a default styling to help users with no design experience get started. There are several options if you want to customize the style:
-* **[Configure the `Layout`](layouts.md)**: Customize the arrangement of your components inside your Vizro dashboard.
+- **[Configure the `Layout`](layouts.md)**: Customize the arrangement of your components inside your Vizro dashboard.
-* **[Apply a theme](themes.md)**: Choose between a dark or light theme.
+- **[Apply a theme](themes.md)**: Choose between a dark or light theme.
-* **[Manage assets](assets.md)**: Enhance your dashboard by adding images, scripts, and stylesheets to your assets folder.
+- **[Manage assets](assets.md)**: Enhance your dashboard by adding images, scripts, and stylesheets to your assets folder.
-* **[Customize CSS](custom-css.md)**: Incorporate custom CSS to deviate from the default styling and create a
-unique appearance for your Vizro dashboard.
+- **[Customize CSS](custom-css.md)**: Incorporate custom CSS to deviate from the default styling and create a unique appearance for your Vizro dashboard.
-* **[Customize your `component`](components.md)**: Change the appearance of components like the [Graph](graph.md), the
-[Table](table.md) and the [AgGrid](table.md), by passing extra arguments. Refer to the relevant user guide for
-more details.
+- **[Customize your `component`](components.md)**: Change the appearance of components like the [Graph](graph.md), the [Table](table.md) and the [AgGrid](table.md), by passing extra arguments. Refer to the relevant user guide for more details.
diff --git a/vizro-core/examples/README.md b/vizro-core/examples/README.md
index 72146bfb7..53cf932b7 100644
--- a/vizro-core/examples/README.md
+++ b/vizro-core/examples/README.md
@@ -4,8 +4,7 @@ Please note that this folder contains only example dashboards that are still **i
### Vizro examples gallery
-To view a comprehensive list of available demos, please visit our [examples gallery](http://vizro.mckinsey.com/).
-There, you can explore a wide range of dashboards and applications created with Vizro.
+To view a comprehensive list of available demos, please visit our [examples gallery](http://vizro.mckinsey.com/). There, you can explore a wide range of dashboards and applications created with Vizro.
diff --git a/vizro-core/examples/visual-vocabulary/README.md b/vizro-core/examples/visual-vocabulary/README.md
index 3b298520e..e59b3103c 100644
--- a/vizro-core/examples/visual-vocabulary/README.md
+++ b/vizro-core/examples/visual-vocabulary/README.md
@@ -2,14 +2,11 @@
### Welcome to our visual vocabulary dashboard! 🎨
-This dashboard serves as a comprehensive guide for selecting and creating various types of charts. It helps you decide
-when to use each chart type, and offers sample Python code using [Plotly](https://plotly.com/python/), and
-instructions for embedding these charts into a [Vizro](https://github.com/mckinsey/vizro) dashboard.
+This dashboard serves as a comprehensive guide for selecting and creating various types of charts. It helps you decide when to use each chart type, and offers sample Python code using [Plotly](https://plotly.com/python/), and instructions for embedding these charts into a [Vizro](https://github.com/mckinsey/vizro) dashboard.
The charts in this dashboard are designed to make it easy for anyone to create beautiful and sophisticated visuals.
-Our goal is to help you understand best practices in data visualization, ensure your charts effectively communicate
-your message, and streamline the creation of high-quality, interactive visualizations.
+Our goal is to help you understand best practices in data visualization, ensure your charts effectively communicate your message, and streamline the creation of high-quality, interactive visualizations.
Created by:
@@ -19,12 +16,9 @@ Created by:
Inspired by:
-- [The FT Visual Vocabulary](https://github.com/Financial-Times/chart-doctor/blob/main/visual-vocabulary/README.md):
- [Alan Smith](https://github.com/alansmithy), [Chris Campbell](https://github.com/digitalcampbell), Ian Bott,
- Liz Faunce, Graham Parrish, Billy Ehrenberg, Paul McCallum, [Martin Stabe](https://github.com/martinstabe).
+- [The FT Visual Vocabulary](https://github.com/Financial-Times/chart-doctor/blob/main/visual-vocabulary/README.md): [Alan Smith](https://github.com/alansmithy), [Chris Campbell](https://github.com/digitalcampbell), Ian Bott, Liz Faunce, Graham Parrish, Billy Ehrenberg, Paul McCallum, [Martin Stabe](https://github.com/martinstabe).
-- [The Graphic Continuum](https://www.informationisbeautifulawards.com/showcase/611-the-graphic-continuum):
- Jon Swabish and Severino Ribecca
+- [The Graphic Continuum](https://www.informationisbeautifulawards.com/showcase/611-the-graphic-continuum): Jon Swabish and Severino Ribecca
Credits and sources:
@@ -102,13 +96,12 @@ The dashboard is still in development. Below is an overview of the chart types f
Contributions are welcome! To contribute a chart, follow the steps below:
1. Check that a `svg` file named after the chart type is contained in the [assets](https://github.com/mckinsey/vizro/tree/main/vizro-core/examples/visual-vocabulary/assets/images/charts) folder. If not, [raise an issue](https://github.com/mckinsey/vizro/issues) in the repository.
-2. Add a `.py` file containing a code example of the chart type in the `pages/examples` folder, for instance, `area.py`. Take a look at existing examples.
-3. Create a new page for the chart type and add it to the relevant category `.py` file such as `correlation.py`,
- `deviation.py`, `distribution.py`, etc. Ensure you add the page to the list of `pages` at the end of the `.py` file.
-4. Remove the `IncompletePage(..)` entry for that chart type in `chart_groups.py`.
-5. Update this `README.md` with the new chart type, its status, category, and API links.
+1. Add a `.py` file containing a code example of the chart type in the `pages/examples` folder, for instance, `area.py`. Take a look at existing examples.
+1. Create a new page for the chart type and add it to the relevant category `.py` file such as `correlation.py`, `deviation.py`, `distribution.py`, etc. Ensure you add the page to the list of `pages` at the end of the `.py` file.
+1. Remove the `IncompletePage(..)` entry for that chart type in `chart_groups.py`.
+1. Update this `README.md` with the new chart type, its status, category, and API links.
## How to run the example locally
1. Run the example with the command `hatch run example visual-vocabulary`.
-2. You should now be able to access the app locally via http://127.0.0.1:8051/.
+1. You should now be able to access the app locally via http://127.0.0.1:8051/.
tag
- type: card
- title: Changing the header color
+ ###### This is an tag
+ type: card
+ title: Changing the header color
```
- === "Result"
- [![AssetsCSS]][AssetsCSS]
-
- [AssetsCSS]: ../../assets/user_guides/assets/css_change.png
+ === "Result"
+ [![AssetsCSS]][assetscss]
### Overwrite CSS for selected pages
-To style components for a specific page, use the page's `id` in the CSS selectors. By default, this is the
-[same as the page `title`](pages.md), but such a value might not be a valid CSS identifier.
-A suitable `id` must be unique across all models in the dashboard and should contain only alphanumeric
-characters, hyphens (`-`) and underscores (`_`). In particular, note that spaces are _not_ allowed.
+To style components for a specific page, use the page's `id` in the CSS selectors. By default, this is the [same as the page `title`](pages.md), but such a value might not be a valid CSS identifier.
+
+A suitable `id` must be unique across all models in the dashboard and should contain only alphanumeric characters, hyphens (`-`) and underscores (`_`). In particular, note that spaces are _not_ allowed.
Suppose you want to hide the page title on one page only. Here's how you can achieve this:
1. Give a valid `id` to the `Page`, for example `Page(id="page-with-hidden-title", title="Page with hidden title", ...)`.
-2. Identify the CSS class or CSS `id` you need to target. To hide the page title, you need to hide the parent container with the id `right-header`.
-3. Use the `id` to hide the content.
-4. Add your custom css file to the `assets` folder.
-
+1. Identify the CSS class or CSS `id` you need to target. To hide the page title, you need to hide the parent container with the id `right-header`.
+1. Use the `id` to hide the content.
+1. Add your custom css file to the `assets` folder.
!!! example "Hide page title on selected pages"
=== "my_css_file.css"
- ```css
- #page-with-hidden-title #right-header {
- display: none;
- }
- ```
+ ```css
+ #page-with-hidden-title #right-header {
+ display: none;
+ }
+ ```
+
=== "app.py"
```py
import vizro.models as vm
@@ -199,25 +185,24 @@ Suppose you want to hide the page title on one page only. Here's how you can ach
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Placeholder
- type: card
- title: Page with hidden title
- id: page-with-hidden-title
- - components:
- - text: |
- # Placeholder
- type: card
- title: Page with shown title
+ - components:
+ - text: |
+ # Placeholder
+ type: card
+ title: Page with hidden title
+ id: page-with-hidden-title
+ - components:
+ - text: |
+ # Placeholder
+ type: card
+ title: Page with shown title
```
- === "Result"
- [![PageTitle]][PageTitle]
-
- [PageTitle]: ../../assets/user_guides/assets/css_page_title.png
+ === "Result"
+ [![PageTitle]][pagetitle]
### Overwrite CSS for selected components
+
To adjust CSS properties for specific components, such as altering the appearance of a selected [`Card`][vizro.models.Card] rather than all Cards, you need to supply an `id` to the component you want to style.
Let's say we want to change the `background-color` and `color` of a specific `Card`.
@@ -225,41 +210,43 @@ Let's say we want to change the `background-color` and `color` of a specific `Ca
Here's how you can do it:
1. Assign a unique `id` to the relevant `Card`, for example: `Card(id="custom-card", ...)`
-2. Run your dashboard and open it in your browser
-3. View the HTML document to find the appropriate CSS class or element you need to target, as explained in the section
-on [identifying the correct CSS selector](#identify-the-correct-css-selector).
+1. Run your dashboard and open it in your browser
+1. View the HTML document to find the appropriate CSS class or element you need to target, as explained in the section on [identifying the correct CSS selector](#identify-the-correct-css-selector).
-It's essential to understand the relationship between the targeted CSS class or element and the component assigned
-`id`, for example:
+It's essential to understand the relationship between the targeted CSS class or element and the component assigned `id`, for example:
-```html title="HTML structure of a `Card`"
+
+```html title="HTML structure of a card"
-
- Lorem ipsum dolor sit amet consectetur adipisicing elit.
-
+
+
+ Lorem ipsum dolor sit amet consectetur adipisicing elit.
+
+
```
-
-* **Main element with `id`:** There is a `` with our `id="custom-card"`.
-* **Parent element:** That `` is wrapped inside a parent `` with the class name `"card"`. This is the element we need to target to change the background color.
-* **Child element:** The card text is wrapped inside a `` that is a child of the `
` with our `id`. This is the element we need to target to change the font color.
+
+- **Main element with `id`:** There is a `` with our `id="custom-card"`.
+- **Parent element:** That `` is wrapped inside a parent `` with the class name `"card"`. This is the element we need to target to change the background color.
+- **Child element:** The card text is wrapped inside a `` that is a child of the `
` with our `id`. This is the element we need to target to change the font color.
!!! example "Customizing CSS properties in selective components"
=== "my_css_file.css"
- ```css
- /* Apply styling to parent */
- .card:has(#custom-card) {
- background-color: white;
- }
+ ```css
+ /* Apply styling to parent */
+ .card:has(#custom-card) {
+ background-color: white;
+ }
+
+ /* Apply styling to child */
+ #custom-card p {
+ color: black;
+ }
+ ```
- /* Apply styling to child */
- #custom-card p {
- color: black;
- }
- ```
=== "app.py"
```py
import vizro.models as vm
@@ -285,77 +272,65 @@ It's essential to understand the relationship between the targeted CSS class or
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- Lorem ipsum dolor sit amet consectetur adipisicing elit.
- type: card
- id: custom-card
- - text: |
- Lorem ipsum dolor sit amet consectetur adipisicing elit.
- type: card
- title: Changing the card color
+ - components:
+ - text: |
+ Lorem ipsum dolor sit amet consectetur adipisicing elit.
+ type: card
+ id: custom-card
+ - text: |
+ Lorem ipsum dolor sit amet consectetur adipisicing elit.
+ type: card
+ title: Changing the card color
```
- === "Result"
- [![CardCSS]][CardCSS]
-
- [CardCSS]: ../../assets/user_guides/assets/css_change_card.png
+ === "Result"
+ [![CardCSS]][cardcss]
!!! note "Relationship between model ID and CSS ID"
+ Some Vizro components produce a single HTML element with an ID that matches the model ID, allowing you to target it directly using the CSS #id selector. Other components generate multiple HTML elements. Within these, the "core" element will have an ID matching the model ID, while non-core elements may have IDs that are variations of it, such as `{model-id}-title`.
- Some Vizro components produce a single HTML element with an ID that matches the model ID, allowing you to target it
- directly using the CSS #id selector. Other components generate multiple HTML elements. Within these, the "core"
- element will have an ID matching the model ID, while non-core elements may have IDs that are variations of it,
- such as `{model-id}-title`.
-
- In all instances, you can determine the correct selector by using Chrome DevTools or a similar tool after setting the
- appropriate model ID.
-
+ In all instances, you can determine the correct selector by using Chrome DevTools or a similar tool after setting the appropriate model ID.
## Common examples
### Make your CSS responsive to theme switches with variables
-To ensure your CSS adapts to theme changes, we recommend using CSS variables (`var`) whenever possible. For a
-comprehensive list of available variable names, refer to the
-[Bootstrap documentation](https://getbootstrap.com/docs/5.3/customize/css-variables/). Note that our
-Bootstrap stylesheet is still under development, so not all Bootstrap variables are currently available.
-Additionally, you can define your own CSS variables, as demonstrated in the example on
-[changing the container background color](#change-the-styling-of-a-container).
+
+To ensure your CSS adapts to theme changes, we recommend using CSS variables (`var`) whenever possible. For a comprehensive list of available variable names, refer to the [Bootstrap documentation](https://getbootstrap.com/docs/5.3/customize/css-variables/). Note that our Bootstrap stylesheet is still under development, so not all Bootstrap variables are currently available. Additionally, you can define your own CSS variables, as demonstrated in the example on [changing the container background color](#change-the-styling-of-a-container).
### Turn off page title
+
See the example above on [hiding the page title on selected pages](#overwrite-css-for-selected-pages).
### Change the background color of a card
+
See the example above on [customizing CSS properties in selective components](#overwrite-css-for-selected-components).
### Change the global font
+
The default fonts for a Vizro app are `Inter, sans-serif, Arial, serif`.
If you need to change the global font, perhaps to adhere to branding guidelines, follow these steps:
1. Download the desired font from a font provider such as [Google Fonts](https://fonts.google.com/).
-2. Place the font file (`.ttf`, `woff2`, etc.) into your `assets` folder. Here’s an example of what the assets folder might look like:
- 
+1. Place the font file (`.ttf`, `woff2`, etc.) into your `assets` folder. Here’s an example of what the assets folder might look like:
-3. Add the font to your CSS file using the `@font-face` rule and apply the font globally to your Vizro app, making sure
-to specify fallback fonts. Add the following to your `custom.css` file:
+ 
+1. Add the font to your CSS file using the `@font-face` rule and apply the font globally to your Vizro app, making sure to specify fallback fonts. Add the following to your `custom.css` file:
```css
@font-face {
- font-family: PlayfairDisplay;
- src: url("PlayfairDisplay-VariableFont_wght.ttf") format("truetype");
+ font-family: PlayfairDisplay;
+ src: url("PlayfairDisplay-VariableFont_wght.ttf") format("truetype");
}
* {
- font-family: PlayfairDisplay, Inter, sans-serif, Arial, serif;
+ font-family: PlayfairDisplay, Inter, sans-serif, Arial, serif;
}
```
-
-4. Note that the modification above applies solely to the dashboard font. To also change the font within the
-Plotly charts, you must specify this at the beginning of your `app.py` file:
+1. Note that the modification above applies solely to the dashboard font. To also change the font within the Plotly charts, you must specify this at the beginning of your `app.py` file:
```python
import plotly.io as pio
@@ -365,44 +340,42 @@ Plotly charts, you must specify this at the beginning of your `app.py` file:
```
### Reposition the logo
-By default, the logo appears in the top left corner of the dashboard. You can move it further to the left or right by
-adjusting the `padding` of the `#page-header` element. Here is an example of how to achieve this:
+
+By default, the logo appears in the top left corner of the dashboard. You can move it further to the left or right by adjusting the `padding` of the `#page-header` element. Here is an example of how to achieve this:
```css
#page-header {
- padding-left: 8px;
+ padding-left: 8px;
}
```
-
### Change the styling of a container
-If you want to make the subsections of your dashboard stand out more, you can do this by placing your components
-inside a [Container](container.md) and changing the container's styling, for example, background color, borders, padding, etc.
-To do this, you need to change the container's CSS class. Using the DevTool, as explained in the section on
-[identifying the correct CSS selector](#identify-the-correct-css-selector), you'll find that the CSS class for the
-`Container` is `page-component-container`. You can then use this class to set a new `background-color` and `padding`.
+If you want to make the subsections of your dashboard stand out more, you can do this by placing your components inside a [Container](container.md) and changing the container's styling, for example, background color, borders, padding, etc.
+
+To do this, you need to change the container's CSS class. Using the DevTool, as explained in the section on [identifying the correct CSS selector](#identify-the-correct-css-selector), you'll find that the CSS class for the `Container` is `page-component-container`. You can then use this class to set a new `background-color` and `padding`.
!!! example "Style a container"
=== "custom.css"
- ```css
- /* Assign a variable to the dark and light theme */
- [data-bs-theme="dark"] {
- --container-bg-color: #232632;
- }
-
- [data-bs-theme="light"] {
- --container-bg-color: #F5F6F6;
- }
+ ```css
+ /* Assign a variable to the dark and light theme */
+ [data-bs-theme="dark"] {
+ --container-bg-color: #232632;
+ }
+
+ [data-bs-theme="light"] {
+ --container-bg-color: #F5F6F6;
+ }
+
+ /* Use the custom variable var(--container-bg-color) */
+ .page-component-container {
+ background: var(--container-bg-color);
+ padding: 12px;
+ }
+ ```
- /* Use the custom variable var(--container-bg-color) */
- .page-component-container {
- background: var(--container-bg-color);
- padding: 12px;
- }
- ```
=== "app.py"
```py
import vizro.models as vm
@@ -437,12 +410,12 @@ To do this, you need to change the container's CSS class. Using the DevTool, as
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - title: "Page with subsections"
+ - title: Page with subsections
layout:
grid: [[0, 1]]
components:
- type: container
- title: "Container I"
+ title: Container I
components:
- type: graph
figure:
@@ -452,7 +425,7 @@ To do this, you need to change the container's CSS class. Using the DevTool, as
y: sepal_length
color: species
- type: container
- title: "Container II"
+ title: Container II
components:
- type: graph
figure:
@@ -462,13 +435,11 @@ To do this, you need to change the container's CSS class. Using the DevTool, as
y: sepal_length
color: species
```
- === "Result"
- [![StyleContainer]][StyleContainer]
- [StyleContainer]: ../../assets/user_guides/custom_css/style-container.png
+ === "Result"
+ [![StyleContainer]][stylecontainer]
-You will notice that the background colors of the charts are different. To align it with the colors of the container,
-you can make the charts' background transparent.
+You will notice that the background colors of the charts are different. To align it with the colors of the container, you can make the charts' background transparent.
To make the background of all charts transparent:
@@ -492,3 +463,8 @@ def custom_chart(data_frame):
```
+
+[assetscss]: ../../assets/user_guides/assets/css_change.png
+[cardcss]: ../../assets/user_guides/assets/css_change_card.png
+[pagetitle]: ../../assets/user_guides/assets/css_page_title.png
+[stylecontainer]: ../../assets/user_guides/custom_css/style-container.png
diff --git a/vizro-core/docs/pages/user-guides/custom-figures.md b/vizro-core/docs/pages/user-guides/custom-figures.md
index f135127be..3a178932f 100644
--- a/vizro-core/docs/pages/user-guides/custom-figures.md
+++ b/vizro-core/docs/pages/user-guides/custom-figures.md
@@ -1,41 +1,36 @@
# How to create custom figures
-This guide explains how to create custom figures, which is useful when you need a component that reacts to
-[filter](filters.md) and [parameter](parameters.md) controls.
+This guide explains how to create custom figures, which is 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).
## When to use a custom figure
-As described in the flowchart detailing [when to use `Figure`](figure.md), custom figures should be used if
-**both** of the following conditions are met:
+
+As described in the flowchart detailing [when to use `Figure`](figure.md), custom figures should be used if **both** of the following conditions are met:
- You need a figure that doesn't fit into the existing pre-defined components ([`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid]).
- You need a figure that isn't available in our pre-defined figure functions [`vizro.figures`](../API-reference/figure-callables.md).
## Steps to create a custom figure
-1. Define a function that returns a [Dash component](https://dash.plotly.com/#open-source-component-libraries).
-This can, but does not need to, be based on code in our pre-defined figure functions in [`vizro.figures`](../API-reference/figure-callables.md).
-2. Decorate it with `@capture("figure")`.
-3. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
-4. The figure should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments
-will not react to dashboard controls such as [`Filter`](filters.md).
-5. Pass your function to the `figure` argument of the [`Figure`][vizro.models.Figure] model.
+1. Define a function that returns a [Dash component](https://dash.plotly.com/#open-source-component-libraries). This can, but does not need to, be based on code in our pre-defined figure functions in [`vizro.figures`](../API-reference/figure-callables.md).
+1. Decorate it with `@capture("figure")`.
+1. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
+1. The figure should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments will not react to dashboard controls such as [`Filter`](filters.md).
+1. Pass your function to the `figure` argument of the [`Figure`][vizro.models.Figure] model.
The following examples can be used as a base to build more sophisticated figures.
## Examples of custom figures
### Custom KPI card
-To change the design or content of our existing KPI (key performance indicator) cards from
-[`vizro.figures`](../API-reference/figure-callables.md), you can do so by following the steps described above.
-For instance, to make a KPI card with the icon positioned on the right side of the title instead of the left,
-copy and paste the [source code of `kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card) and
-adjust the return statement of the function.
+To change the design or content of our existing KPI (key performance indicator) cards from [`vizro.figures`](../API-reference/figure-callables.md), you can do so by following the steps described above.
+
+For instance, to make a KPI card with the icon positioned on the right side of the title instead of the left, copy and paste the [source code of `kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card) and adjust the return statement of the function.
+
!!! example "Custom KPI card"
=== "app.py"
```{.python pycafe-link}
@@ -107,29 +102,26 @@ adjust the return statement of the function.
```
1. Here we decorate our custom figure function with the `@capture("figure")` decorator.
- 2. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
- 3. We adjust the return statement to include the icon on the right side of the title. This is achieved by swapping the order of the `html.H2` and `html.P` compared to the original `kpi_card`.
- 4. This creates a [`layout`](layouts.md) with four rows and columns. The KPI cards are positioned in the first two cells, while the remaining cells are empty.
- 5. For more information, refer to the API reference for the [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card).
- 6. Our custom figure function `custom_kpi_card` now needs to be passed on to the `vm.Figure`.
+ 1. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
+ 1. We adjust the return statement to include the icon on the right side of the title. This is achieved by swapping the order of the `html.H2` and `html.P` compared to the original `kpi_card`.
+ 1. This creates a [`layout`](layouts.md) with four rows and columns. The KPI cards are positioned in the first two cells, while the remaining cells are empty.
+ 1. For more information, refer to the API reference for the [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card).
+ 1. Our custom figure function `custom_kpi_card` now needs to be passed on to the `vm.Figure`.
=== "app.yaml"
- ```yaml
- # Custom figures are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomKPI]][CustomKPI]
+ Custom figures are currently only possible via Python configuration.
- [CustomKPI]: ../../assets/user_guides/figure/custom_kpi.png
+ === "Result"
+ [![CustomKPI]][customkpi]
### Dynamic HTML header
-You can create a custom figure for any [Dash component](https://dash.plotly.com/#open-source-component-libraries).
-Below is an example of a custom figure that returns a `html.H2` component that dynamically updates based on the selected
-name from a filter.
+
+You can create a custom figure for any [Dash component](https://dash.plotly.com/#open-source-component-libraries). Below is an example of a custom figure that returns a `html.H2` component that dynamically updates based on the selected name from a filter.
+
!!! example "Dynamic HTML header"
=== "app.py"
```{.python pycafe-link}
@@ -159,27 +151,24 @@ name from a filter.
```
1. Here we decorate our custom figure function with the `@capture("figure")` decorator.
- 2. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
- 3. We return a `html.H2` component that dynamically updates based on the selected name from the filter.
- 4. Our custom figure function `dynamic_html_header` now needs to be passed on to the `vm.Figure`.
+ 1. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
+ 1. We return a `html.H2` component that dynamically updates based on the selected name from the filter.
+ 1. Our custom figure function `dynamic_html_header` now needs to be passed on to the `vm.Figure`.
=== "app.yaml"
- ```yaml
- # Custom figures are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomHTML]][CustomHTML]
+ Custom figures are currently only possible via Python configuration.
- [CustomHTML]: ../../assets/user_guides/figure/custom_html.png
+ === "Result"
+ [![CustomHTML]][customhtml]
-
### Dynamic number of cards
-The example below shows how to create multiple cards created from a `pandas.DataFrame` where the
-number of cards displayed dynamically adjusts based on a `vm.Parameter`.
+
+The example below shows how to create multiple cards created from a `pandas.DataFrame` where the number of cards displayed dynamically adjusts based on a `vm.Parameter`.
+
!!! example "Dynamic number of cards"
=== "app.py"
```py
@@ -239,40 +228,39 @@ number of cards displayed dynamically adjusts based on a `vm.Parameter`.
```
1. Here we decorate our custom figure function with the `@capture("figure")` decorator.
- 2. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
- 3. Our decorated figure function `multiple_cards` now needs to be passed on to the `vm.Figure`.
- 4. We add a [`vm.Parameter`](parameters.md) to dynamically adjust the number of cards displayed.
- The parameter targets the `n_rows` argument of the `multiple_cards` function, determining the number of rows
- taken from the data.
+ 1. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
+ 1. Our decorated figure function `multiple_cards` now needs to be passed on to the `vm.Figure`.
+ 1. We add a [`vm.Parameter`](parameters.md) to dynamically adjust the number of cards displayed. The parameter targets the `n_rows` argument of the `multiple_cards` function, determining the number of rows taken from the data.
Run and edit this code in PyCafe
=== "styling.css"
```css
.multiple-cards-container {
- display: flex;
- flex-wrap: wrap;
- gap: 12px;
+ display: flex;
+ flex-wrap: wrap;
+ gap: 12px;
}
.figure-container {
- height: unset;
- width: unset;
+ height: unset;
+ width: unset;
}
.figure-container .card {
- height: 210px;
- width: 240px;
+ height: 210px;
+ width: 240px;
}
```
- === "app.yaml"
- ```yaml
- # Custom figures are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomFigure]][CustomFigure]
- [CustomFigure]: ../../assets/user_guides/figure/custom_multiple_cards.png
+ === "app.yaml"
+ Custom figures are currently only possible via Python configuration.
+ === "Result"
+ [![CustomFigure]][customfigure]
+
+[customfigure]: ../../assets/user_guides/figure/custom_multiple_cards.png
+[customhtml]: ../../assets/user_guides/figure/custom_html.png
+[customkpi]: ../../assets/user_guides/figure/custom_kpi.png
diff --git a/vizro-core/docs/pages/user-guides/custom-tables.md b/vizro-core/docs/pages/user-guides/custom-tables.md
index e990cfbb0..42748820b 100644
--- a/vizro-core/docs/pages/user-guides/custom-tables.md
+++ b/vizro-core/docs/pages/user-guides/custom-tables.md
@@ -1,21 +1,18 @@
# How to create custom Dash AG Grids and Dash DataTables
-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.
+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.
-The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] model accept the `figure` argument, where you can enter
-_any_ [`dash_ag_grid`][vizro.tables.dash_ag_grid] or [`dash_data_table`][vizro.tables.dash_data_table] chart as explained in the [user guide on tables](table.md).
+The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] model accept the `figure` argument, where you can enter _any_ [`dash_ag_grid`][vizro.tables.dash_ag_grid] or [`dash_data_table`][vizro.tables.dash_data_table] chart as explained in the [user guide on tables](table.md).
One reason could be that you want to create a table/grid that requires computations that can be controlled by parameters (see the example below).
### Steps to create a custom table
1. Define a function that returns a `dash_ag_grid.AgGrid` or `dash_table.DataTable` object.
-2. Decorate it with `@capture("ag_grid")` or `@capture("table")`.
-3. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
-4. The table should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments
-will not react to dashboard controls such as [`Filter`](filters.md).
-5. Pass your function to the `figure` argument of the [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid] model.
+1. Decorate it with `@capture("ag_grid")` or `@capture("table")`.
+1. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
+1. The table should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments will not react to dashboard controls such as [`Filter`](filters.md).
+1. Pass your function to the `figure` argument of the [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid] model.
The following examples show a possible version of a custom table. In this case the argument `chosen_columns` was added, which you can control with a parameter:
@@ -70,14 +67,12 @@ The following examples show a possible version of a custom table. In this case t
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
- ```yaml
- # Custom tables are currently only possible via Python configuration
- ```
- === "Result"
- [![Table3]][Table3]
+ Custom tables are currently only possible via Python configuration.
- [Table3]: ../../assets/user_guides/table/custom_table.png
+ === "Result"
+ [![Table3]][table3]
??? example "Custom Dash AgGrid"
=== "app.py"
@@ -136,11 +131,12 @@ The following examples show a possible version of a custom table. In this case t
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
- ```yaml
- # Custom Ag Grids are currently only possible via Python configuration
- ```
+ Custom Ag Grids are currently only possible via Python configuration.
+
=== "Result"
- [![GridCustom]][GridCustom]
+ [![GridCustom]][gridcustom]
- [GridCustom]: ../../assets/user_guides/table/custom_grid.png
+[gridcustom]: ../../assets/user_guides/table/custom_grid.png
+[table3]: ../../assets/user_guides/table/custom_table.png
diff --git a/vizro-core/docs/pages/user-guides/dashboard.md b/vizro-core/docs/pages/user-guides/dashboard.md
index 0b37e03fa..244f65256 100644
--- a/vizro-core/docs/pages/user-guides/dashboard.md
+++ b/vizro-core/docs/pages/user-guides/dashboard.md
@@ -1,16 +1,15 @@
# How to create a dashboard
-This guide shows you how to configure and call a [`Dashboard`][vizro.models.Dashboard] using either
-pydantic models, Python dictionaries, YAML, or JSON.
+
+This guide shows you how to configure and call a [`Dashboard`][vizro.models.Dashboard] using either pydantic models, Python dictionaries, YAML, or JSON.
To create a dashboard:
1. Choose one of the possible configuration syntaxes
-2. Create your `pages`, see our [guide on Pages](pages.md)
-3. (optional) Choose a `theme`, see our [guide on Themes](themes.md)
-4. (optional) Customize your `navigation`, see our [guide on Navigation](navigation.md)
-5. (optional) Set a `title` for your dashboard
-6. Add your `dashboard` to the `build` call of Vizro
-
+1. Create your `pages`, see our [guide on Pages](pages.md)
+1. (optional) Choose a `theme`, see our [guide on Themes](themes.md)
+1. (optional) Customize your `navigation`, see our [guide on Navigation](navigation.md)
+1. (optional) Set a `title` for your dashboard
+1. Add your `dashboard` to the `build` call of Vizro
## Use dashboard configuration options
@@ -37,6 +36,7 @@ To create a dashboard:
Vizro().build(dashboard).run()
```
+
=== "app.py - Python dict"
```py
import vizro.plotly.express as px
@@ -77,6 +77,7 @@ To create a dashboard:
Vizro().build(dashboard).run()
```
+
=== "dashboard.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -101,50 +102,49 @@ To create a dashboard:
type: filter
title: My first dashboard
```
+
=== "dashboard.json"
```json
{
- "pages": [
+ "pages": [
+ {
+ "components": [
+ {
+ "figure": {
+ "_target_": "scatter",
+ "color": "species",
+ "data_frame": "iris",
+ "x": "sepal_length",
+ "y": "petal_width"
+ },
+ "type": "graph"
+ },
{
- "components": [
- {
- "figure": {
- "_target_": "scatter",
- "color": "species",
- "data_frame": "iris",
- "x": "sepal_length",
- "y": "petal_width"
- },
- "type": "graph"
- },
- {
- "figure": {
- "_target_": "histogram",
- "color": "species",
- "data_frame": "iris",
- "x": "sepal_width",
- },
- "type": "graph"
- }
- ],
- "controls": [
- {
- "column": "species",
- "type": "filter"
- }
- ],
- "title": "My first dashboard"
+ "figure": {
+ "_target_": "histogram",
+ "color": "species",
+ "data_frame": "iris",
+ "x": "sepal_width"
+ },
+ "type": "graph"
}
- ]
+ ],
+ "controls": [
+ {
+ "column": "species",
+ "type": "filter"
+ }
+ ],
+ "title": "My first dashboard"
+ }
+ ]
}
```
- === "Result"
- [![Dashboard]][Dashboard]
- [Dashboard]: ../../assets/user_guides/dashboard/dashboard.png
+ === "Result"
+ [![Dashboard]][dashboard]
!!! note "Extra `.py` files for `yaml` and `json` required"
-
Note that in the `yaml` and `json` example an extra `.py` is required to register the data and parse the yaml/json configuration.
=== "app.py for yaml"
@@ -164,6 +164,7 @@ To create a dashboard:
Vizro().build(dashboard).run()
```
+
=== "app.py for json"
```py
import json
@@ -187,7 +188,6 @@ After running the dashboard, you can access the dashboard via `localhost:8050`.
If supplied, the `title` of the [`Dashboard`][vizro.models.Dashboard] displays a heading at the top of every page.
-
## Add a dashboard logo
Vizro will [automatically incorporate the dashboard logo](assets.md/#add-a-logo-image) in the top-left corner of each page if an image named `logo.` is present within the assets folder.
@@ -196,11 +196,10 @@ Vizro will [automatically incorporate the dashboard logo](assets.md/#add-a-logo-
## Browser title
-The [website icon](assets.md/#change-the-favicon), Dashboard `title` (if supplied) and [Page `title`][vizro.models.Page] are displayed in the browser's
-title bar. For example, if your Dashboard `title` is "Vizro Demo" and the Page `title` is "Homepage", then the title in the browser tab will be "Vizro Demo: Homepage".
+The [website icon](assets.md/#change-the-favicon), Dashboard `title` (if supplied) and [Page `title`][vizro.models.Page] are displayed in the browser's title bar. For example, if your Dashboard `title` is "Vizro Demo" and the Page `title` is "Homepage", then the title in the browser tab will be "Vizro Demo: Homepage".
## Meta tags for social media
-Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat
-clients. The preview includes the `URL`, `title`, plus an [image](assets.md/#include-a-meta-tags-image) and
-[Page `description`][vizro.models.Page] (if supplied). To see an example, try sharing an example from the [Vizro examples gallery](https://vizro.mckinsey.com/).
+Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat clients. The preview includes the `URL`, `title`, plus an [image](assets.md/#include-a-meta-tags-image) and [Page `description`][vizro.models.Page] (if supplied). To see an example, try sharing an example from the [Vizro examples gallery](https://vizro.mckinsey.com/).
+
+[dashboard]: ../../assets/user_guides/dashboard/dashboard.png
diff --git a/vizro-core/docs/pages/user-guides/data.md b/vizro-core/docs/pages/user-guides/data.md
index 51bf84b97..d19b8aafb 100644
--- a/vizro-core/docs/pages/user-guides/data.md
+++ b/vizro-core/docs/pages/user-guides/data.md
@@ -2,11 +2,12 @@
Vizro supports two different types of data:
-* [Static data](#static-data): pandas DataFrame. This is the simplest method and best to use if you do not need the more advanced functionality of dynamic data.
-* [Dynamic data](#dynamic-data): function that returns a pandas DataFrame. This is a bit more complex to understand but has more advanced functionality such as the ability to refresh data while the dashboard is running.
+- [Static data](#static-data): pandas DataFrame. This is the simplest method and best to use if you do not need the more advanced functionality of dynamic data.
+- [Dynamic data](#dynamic-data): function that returns a pandas DataFrame. This is a bit more complex to understand but has more advanced functionality such as the ability to refresh data while the dashboard is running.
The following flowchart shows what you need to consider when choosing how to set up your data.
-``` mermaid
+
+```mermaid
graph TD
refresh["`Do you need your data to refresh while the dashboard is running?`"]
specification["`Do you need to specify your dashboard through a configuration language like YAML?`"]
@@ -27,11 +28,10 @@ graph TD
```
??? note "Static vs. dynamic data comparison"
-
This table gives a full comparison between static and dynamic data. Do not worry if you do not yet understand everything in it; it will become clearer after reading more about [static data](#static-data) and [dynamic data](#dynamic-data)!
| | Static | Dynamic |
- |---------------------------------------------------------------|------------------|------------------------------------------|
+ | ------------------------------------------------------------- | ---------------- | ---------------------------------------- |
| Required Python type | pandas DataFrame | Function that returns a pandas DataFrame |
| Can be supplied directly in `data_frame` argument of `figure` | Yes | No |
| Can be referenced by name after adding to data manager | Yes | Yes |
@@ -73,14 +73,13 @@ The below example uses the Iris data saved to a file `iris.csv` in the same dire
```
1. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
- === "Result"
- [![DataBasic]][DataBasic]
- [DataBasic]: ../../assets/user_guides/data/data_pandas_dataframe.png
+ === "Result"
+ [![DataBasic]][databasic]
The [`Graph`][vizro.models.Graph], [`AgGrid`][vizro.models.AgGrid] and [`Table`][vizro.models.Table] models all have an argument called `figure`. This accepts a function (in the above example, `px.scatter`) that takes a pandas DataFrame as its first argument. The name of this argument is always `data_frame`. When configuring the dashboard using Python, it is optional to give the name of the argument: if you like, you could write `data_frame=iris` instead of `iris`.
-!!! note
+!!! note
With static data, once the dashboard is running, the data shown in the dashboard cannot change even if the source data in `iris.csv` changes. The code `iris = pd.read_csv("iris.csv")` is only executed once when the dashboard is first started. If you would like changes to source data to flow through to the dashboard then you must use [dynamic data](#dynamic-data).
### Reference by name
@@ -107,27 +106,27 @@ If you would like to specify your dashboard configuration through YAML then you
```
1. `"iris"` is the name of a data source added to the data manager. This data is a pandas DataFrame created by reading from the CSV file `iris.csv`.
+
=== "dashboard.yaml"
```yaml
pages:
- - components:
- - figure:
+ - components:
+ figure:
_target_: box
data_frame: iris # (1)!
x: species
y: petal_width
color: species
type: graph
- title: Static data example
+ title: Static data example
```
1. Refer to the `"iris"` data source in the data manager.
- === "Result"
- [![DataBasic]][DataBasic]
- [DataBasic]: ../../assets/user_guides/data/data_pandas_dataframe.png
+ === "Result"
+ [![DataBasic]][databasic]
-It is also possible to refer to a named data source using the Python API: `px.scatter("iris", ...)` or `px.scatter(data_frame="iris", ...)` would work if the `"iris"` data source has been registered in the data manager.
+It is also possible to refer to a named data source using the Python API: `px.scatter("iris", ...)` or `px.scatter(data_frame="iris", ...)` would work if the `"iris"` data source has been registered in the data manager.
## Dynamic data
@@ -166,14 +165,12 @@ The example below shows how data is fetched dynamically every time the page is r
```
1. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
- 2. To demonstrate that dynamic data can change when the page is refreshed, select 50 points at random. This simulates what would happen if your file `iris.csv` were constantly changing.
- 3. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()`; doing so would result in static data that cannot be reloaded.
- 4. Dynamic data is referenced by the name of the data source `"iris"`.
+ 1. To demonstrate that dynamic data can change when the page is refreshed, select 50 points at random. This simulates what would happen if your file `iris.csv` were constantly changing.
+ 1. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()`; doing so would result in static data that cannot be reloaded.
+ 1. Dynamic data is referenced by the name of the data source `"iris"`.
=== "Result"
- [![DynamicData]][DynamicData]
-
- [DynamicData]: ../../assets/user_guides/data/dynamic_data.gif
+ [![DynamicData]][dynamicdata]
Since dynamic data sources must always be added to the data manager and referenced by name, they may be used in YAML configuration [exactly the same way as for static data sources](#reference-by-name).
@@ -184,10 +181,10 @@ By default, a dynamic data function executes every time the dashboard is refresh
The Vizro data manager has a server-side caching mechanism to help solve this. Vizro's cache uses [Flask-Caching](https://flask-caching.readthedocs.io/en/latest/), which supports a number of possible cache backends and [configuration options](https://flask-caching.readthedocs.io/en/latest/#configuring-flask-caching). By default, the cache is turned off.
+
In a development environment the easiest way to enable caching is to use a [simple memory cache](https://cachelib.readthedocs.io/en/stable/simple/) with the default configuration options. This is achieved by adding one line to the above example to set `data_manager.cache`:
!!! example "Simple cache with default timeout of 5 minutes"
-
```py hl_lines="13"
from flask_caching import Cache
from vizro import Vizro
@@ -225,7 +222,6 @@ data_manager.cache = Cache(config={"CACHE_TYPE": "SimpleCache", "CACHE_DEFAULT_T
```
!!! warning
-
Simple cache exists purely for single-process development purposes and is not intended to be used in production. If you deploy with multiple workers, [for example with Gunicorn](run.md/#gunicorn), then you should use a production-ready cache backend. All of Flask-Caching's [built-in backends](https://flask-caching.readthedocs.io/en/latest/#built-in-cache-backends) other than `SimpleCache` are suitable for production. In particular, you might like to use [`FileSystemCache`](https://cachelib.readthedocs.io/en/stable/file/) or [`RedisCache`](https://cachelib.readthedocs.io/en/stable/redis/):
```py title="Production-ready caches"
@@ -239,7 +235,9 @@ data_manager.cache = Cache(config={"CACHE_TYPE": "SimpleCache", "CACHE_DEFAULT_T
Since Flask-Caching relies on [`pickle`](https://docs.python.org/3/library/pickle.html), which can execute arbitrary code during unpickling, you should not cache data from untrusted sources. Doing so [could be unsafe](https://github.com/pallets-eco/flask-caching/pull/209).
Note that when a production-ready cache backend is used, the cache is persisted beyond the Vizro process and is not cleared by restarting your server. To clear the cache then you must do so manually, for example, if you use `FileSystemCache` then you would delete your `cache` directory. Persisting the cache can also be useful for development purposes when handling data that takes a long time to load: even if you do not need the data to refresh while your dashboard is running, it can speed up your development loop to use dynamic data with a cache that is persisted between repeated runs of Vizro.
+
+
#### Set timeouts
You can change the timeout of the cache independently for each dynamic data source in the data manager using the `timeout` setting (measured in seconds). A `timeout` of 0 indicates that the cache does not expire. This is effectively the same as using [static data](#static-data).
@@ -278,8 +276,8 @@ In general, a parametrized dynamic data source should always return a pandas Dat
To add a parameter to control a dynamic data source, do the following:
1. add the appropriate argument to your dynamic data function and specify a default value for the argument.
-2. give an `id` to all components that have the data source you wish to alter through a parameter.
-3. [add a parameter](parameters.md) with `targets` of the form `.data_frame.` and a suitable [selector](selectors.md).
+1. give an `id` to all components that have the data source you wish to alter through a parameter.
+1. [add a parameter](parameters.md) with `targets` of the form `.data_frame.` and a suitable [selector](selectors.md).
For example, let us extend the [dynamic data example](#dynamic-data) above into an example of how parametrized dynamic data works. The `load_iris_data` can take an argument `number_of_points` controlled from the dashboard with a [`Slider`][vizro.models.Slider].
@@ -318,21 +316,18 @@ For example, let us extend the [dynamic data example](#dynamic-data) above into
```
1. `load_iris_data` takes a single argument, `number_of_points`, with a default value of 10.
- 2. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
- 3. Sample points at random, where `number_of_points` gives the number of points selected.
- 4. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()` or `load_iris_data(number_of_points=...)`; doing so would result in static data that cannot be reloaded.
- 5. Give the `vm.Graph` component `id="graph"` so that the `vm.Parameter` can target it. Dynamic data is referenced by the name of the data source `"iris"`.
- 6. Create a `vm.Parameter` to target the `number_of_points` argument for the `data_frame` used in `graph`.
+ 1. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
+ 1. Sample points at random, where `number_of_points` gives the number of points selected.
+ 1. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()` or `load_iris_data(number_of_points=...)`; doing so would result in static data that cannot be reloaded.
+ 1. Give the `vm.Graph` component `id="graph"` so that the `vm.Parameter` can target it. Dynamic data is referenced by the name of the data source `"iris"`.
+ 1. Create a `vm.Parameter` to target the `number_of_points` argument for the `data_frame` used in `graph`.
=== "Result"
- [![ParametrizedDynamicData]][ParametrizedDynamicData]
-
- [ParametrizedDynamicData]: ../../assets/user_guides/data/parametrized_dynamic_data.gif
+ [![ParametrizedDynamicData]][parametrizeddynamicdata]
Parametrized data loading is compatible with [caching](#configure-cache). The cache uses [memoization](https://flask-caching.readthedocs.io/en/latest/#memoization), so that the dynamic data function's arguments are included in the cache key. This means that `load_iris_data(number_of_points=10)` is cached independently of `load_iris_data(number_of_points=20)`.
!!! warning
-
You should always [treat the content of user input as untrusted](https://community.plotly.com/t/writing-secure-dash-apps-community-thread/54619). For example, you should not expose a filepath to load without passing it through a function like [`werkzeug.utils.secure_filename`](https://werkzeug.palletsprojects.com/en/3.0.x/utils/#werkzeug.utils.secure_filename), or you might enable arbitrary access to files on your server.
You cannot pass [nested parameters](parameters.md#nested-parameters) to dynamic data. You can only target the top-level arguments of the data loading function, not the nested keys in a dictionary.
@@ -354,7 +349,6 @@ When the page is refreshed, the behavior of a dynamic filter is as follows:
For example, let us add two filters to the [dynamic data example](#dynamic-data) above:
!!! example "Dynamic filters"
-
```py hl_lines="10 20 21"
from vizro import Vizro
import pandas as pd
@@ -386,8 +380,8 @@ For example, let us add two filters to the [dynamic data example](#dynamic-data)
```
1. We sample only 5 rather than 50 points so that changes to the available values in the filtered columns are more apparent when the page is refreshed.
- 2. This filter implicitly controls the dynamic data source `"iris"`, which supplies the `data_frame` to the targeted `vm.Graph`. On page refresh, Vizro reloads this data, finds all the unique values in the `"species"` column and sets the categorical selector's `options` accordingly.
- 3. Similarly, on page refresh, Vizro finds the minimum and maximum values of the `"sepal_length"` column in the reloaded data and sets new `min` and `max` values for the numerical selector accordingly.
+ 1. This filter implicitly controls the dynamic data source `"iris"`, which supplies the `data_frame` to the targeted `vm.Graph`. On page refresh, Vizro reloads this data, finds all the unique values in the `"species"` column and sets the categorical selector's `options` accordingly.
+ 1. Similarly, on page refresh, Vizro finds the minimum and maximum values of the `"sepal_length"` column in the reloaded data and sets new `min` and `max` values for the numerical selector accordingly.
Consider a filter that depends on dynamic data, where you do **not** want the available values to change when the dynamic data changes. You should manually specify the `selector`'s `options` field (categorical selector) or `min` and `max` fields (numerical selector). In the above example, this could be achieved as follows:
@@ -409,10 +403,13 @@ controls = [
When Vizro initially builds a filter that depends on parametrized dynamic data loading, data is loaded using the default argument values. This data is used to:
-* perform initial validation
-* check which data sources contain the specified `column` (unless `targets` is explicitly specified) and
-* find the type of selector to use (unless `selector` is explicitly specified).
+- perform initial validation
+- check which data sources contain the specified `column` (unless `targets` is explicitly specified) and
+- find the type of selector to use (unless `selector` is explicitly specified).
!!! note
-
When the value of a dynamic data parameter is changed by a dashboard user, the data underlying a dynamic filter can change. Currently this change affects page components such as `vm.Graph` but does not affect the available values shown in a dynamic filter, which only update on page refresh. This functionality will be coming soon!
+
+[databasic]: ../../assets/user_guides/data/data_pandas_dataframe.png
+[dynamicdata]: ../../assets/user_guides/data/dynamic_data.gif
+[parametrizeddynamicdata]: ../../assets/user_guides/data/parametrized_dynamic_data.gif
diff --git a/vizro-core/docs/pages/user-guides/extensions.md b/vizro-core/docs/pages/user-guides/extensions.md
index 2c7efc9ac..74a740448 100644
--- a/vizro-core/docs/pages/user-guides/extensions.md
+++ b/vizro-core/docs/pages/user-guides/extensions.md
@@ -2,64 +2,49 @@
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).
+- **[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.
+- **[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.
-* **[CSS customizations](#css-customizations)**. You can add custom CSS to any Vizro dashboard, enabling users to deviate from the default styling and create a unique look and feel for their dashboard.
-
-* **[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
+- **[CSS customizations](#css-customizations)**. You can add custom CSS to any Vizro dashboard, enabling users to deviate from the default styling and create a unique look and feel for their dashboard.
+- **[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
-
+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)).
+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.
-
+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).
+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
+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:
+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
@@ -93,14 +78,12 @@ enabling an interaction between data points in a scatter plot and the content of
## CSS customizations
-Vizro is opinionated about visual formatting, and some elements, such as the layout of the navigation and controls,
-are fixed. You can customize some settings such as background colors, fonts, and other styles via CSS overrides.
+Vizro is opinionated about visual formatting, and some elements, such as the layout of the navigation and controls, are fixed. You can customize some settings such as background colors, fonts, and other styles via CSS overrides.
For more information, see our documentation on [customizing CSS](custom-css.md)
## 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
+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)
diff --git a/vizro-core/docs/pages/user-guides/figure.md b/vizro-core/docs/pages/user-guides/figure.md
index 0589fad3b..03bfa412a 100644
--- a/vizro-core/docs/pages/user-guides/figure.md
+++ b/vizro-core/docs/pages/user-guides/figure.md
@@ -1,26 +1,19 @@
# How to use figures
-This guide shows you how to add any [Dash component](https://dash.plotly.com/#open-source-component-libraries) that needs to be reactive to [filter](filters.md) and [parameter](parameters.md) controls.
-If you want to add a static Dash component to your page, use [custom components](custom-components.md) instead.
+This guide shows you how to add any [Dash component](https://dash.plotly.com/#open-source-component-libraries) that needs to be reactive to [filter](filters.md) and [parameter](parameters.md) controls. If you want to add a static Dash component to your page, use [custom components](custom-components.md) instead.
-[`Figure`][vizro.models.Figure] provides a flexible foundation for all types of reactive Dash components in Vizro.
-The [`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] and [`AgGrid`][vizro.models.AgGrid] components are
-specific implementations of `Figure`. They serve as intuitive shortcuts, embedding behaviors and interactions specific
-to their purposes.
+[`Figure`][vizro.models.Figure] provides a flexible foundation for all types of reactive Dash components in Vizro. The [`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] and [`AgGrid`][vizro.models.AgGrid] components are specific implementations of `Figure`. They serve as intuitive shortcuts, embedding behaviors and interactions specific to their purposes.
-If these more specific models already achieve what you need then they should be used in preference to
-the more generic `Figure`. Remember that it is possible to supply [custom charts](custom-charts.md) to `Graph`
-and [custom tables](custom-tables.md) to `Table`.
+If these more specific models already achieve what you need then they should be used in preference to the more generic `Figure`. Remember that it is possible to supply [custom charts](custom-charts.md) to `Graph` and [custom tables](custom-tables.md) to `Table`.
-There are already a few figure functions you can reuse, see the section on [KPI cards](#key-performance-indicator-kpi-cards)
-for more details:
+There are already a few figure functions you can reuse, see the section on [KPI cards](#key-performance-indicator-kpi-cards) for more details:
- [`kpi_card`][vizro.figures.kpi_card]
- [`kpi_card_reference`][vizro.figures.kpi_card_reference]
The following flowchart shows what you need to consider when choosing which model to use:
-``` mermaid
+```mermaid
graph TD
first["`Does your desired component exist in Vizro, e.g. Graph, Table or AgGrid?`"]
specific-component([Use the specific component])
@@ -40,14 +33,12 @@ graph TD
classDef clickable color:#4051b5;
```
-
To add a `Figure` to your page:
1. Add the `Figure` model to the components argument of the [Page][vizro.models.Page] model.
-2. Use an existing figure function from [`vizro.figures`](../API-reference/figure-callables.md) and pass it to the `figure` argument of the `Figure` model.
+1. Use an existing figure function from [`vizro.figures`](../API-reference/figure-callables.md) and pass it to the `figure` argument of the `Figure` model.
!!! example "Use existing figure functions"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -99,40 +90,25 @@ To add a `Figure` to your page:
selector:
type: radio_items
layout:
- grid:
- [
- [0, -1, -1, -1],
- [-1, -1, -1, -1],
- [-1, -1, -1, -1],
- [-1, -1, -1, -1],
- [-1, -1, -1, -1],
- ]
+ grid: [[0, -1, -1, -1], [-1, -1, -1, -1], [-1, -1, -1, -1], [-1, -1, -1, -1],
+ [-1, -1, -1, -1]]
title: KPI card
```
- === "Result"
- [![Figure]][Figure]
-
- [Figure]: ../../assets/user_guides/figure/figure.png
+ === "Result"
+ [![Figure]][figure]
### Key Performance Indicator (KPI) cards
-A KPI card is a dynamic card that can display a single value, but optionally, can also include a title, icon, and reference value.
-It is a common visual component to display key metrics in a dashboard. Vizro supports two pre-defined KPI card functions:
-- [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card): A KPI card that shows a single value found
-by performing an aggregation function (by default, `sum`) over a specified column.
-Required arguments are `data_frame` and `value_column`.
+A KPI card is a dynamic card that can display a single value, but optionally, can also include a title, icon, and reference value. It is a common visual component to display key metrics in a dashboard. Vizro supports two pre-defined KPI card functions:
-- [`kpi_card_with_reference`](../API-reference/figure-callables.md#vizro.figures.kpi_card_reference): A KPI card that shows a single value
-and a delta comparison to a reference value found by performing an aggregation function (by default, `sum`) over the specified columns.
-Required arguments are `data_frame`, `value_column` and `reference_column`.
+- [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card): A KPI card that shows a single value found by performing an aggregation function (by default, `sum`) over a specified column. Required arguments are `data_frame` and `value_column`.
-As described in the [API reference](../API-reference/figure-callables.md) and illustrated in the below example, these
-functions have several arguments to customize your KPI cards. If you require a level of customization that is not
-possible with the built-in functions then you can create a [custom figure](custom-figures.md).
+- [`kpi_card_with_reference`](../API-reference/figure-callables.md#vizro.figures.kpi_card_reference): A KPI card that shows a single value and a delta comparison to a reference value found by performing an aggregation function (by default, `sum`) over the specified columns. Required arguments are `data_frame`, `value_column` and `reference_column`.
-!!! example "KPI card variations"
+As described in the [API reference](../API-reference/figure-callables.md) and illustrated in the below example, these functions have several arguments to customize your KPI cards. If you require a level of customization that cannot be done with the built-in functions then you can create a [custom figure](custom-figures.md).
+!!! example "KPI card variations"
=== "app.py"
```{.python pycafe-link}
import pandas as pd
@@ -258,8 +234,8 @@ possible with the built-in functions then you can create a [custom figure](custo
value_column: Actual
reference_column: Reference
title: KPI reference with formatting
- value_format: "{value:.2f}€"
- reference_format: "{delta:+.2f}€ vs. last year ({reference:.2f}€)"
+ value_format: '{value:.2f}€'
+ reference_format: '{delta:+.2f}€ vs. last year ({reference:.2f}€)'
type: figure
- figure:
_target_: kpi_card_reference
@@ -276,7 +252,9 @@ possible with the built-in functions then you can create a [custom figure](custo
grid: [[0, 1, 2, 3], [4, 5, 6, 7], [-1, -1, -1, -1], [-1, -1, -1, -1]]
title: KPI cards
```
+
=== "Result"
- [![KPICards]][KPICards]
+ [![KPICards]][kpicards]
- [KPICards]: ../../assets/user_guides/figure/kpi_cards.png
+[figure]: ../../assets/user_guides/figure/figure.png
+[kpicards]: ../../assets/user_guides/figure/kpi_cards.png
diff --git a/vizro-core/docs/pages/user-guides/filters.md b/vizro-core/docs/pages/user-guides/filters.md
index bc3649178..8228ecbe7 100644
--- a/vizro-core/docs/pages/user-guides/filters.md
+++ b/vizro-core/docs/pages/user-guides/filters.md
@@ -2,8 +2,7 @@
This guide shows you how to add filters to your dashboard. One main way to interact with the charts/components on your page is by filtering the underlying data. A filter selects a subset of rows of a component's underlying DataFrame which alters the appearance of that component on the page.
-The [`Page`][vizro.models.Page] model accepts the `controls` argument, where you can enter a [`Filter`][vizro.models.Filter] model.
-This model enables the automatic creation of [selectors](selectors.md) (for example, `Dropdown` or `RangeSlider`) that operate on the charts/components on the screen.
+The [`Page`][vizro.models.Page] model accepts the `controls` argument, where you can enter a [`Filter`][vizro.models.Filter] model. This model enables the automatic creation of [selectors](selectors.md) (for example, `Dropdown` or `RangeSlider`) that operate on the charts/components on the screen.
By default, filters that control components with [dynamic data](data.md#dynamic-data) are [dynamically updated](data.md#filters) when the underlying data changes while the dashboard is running.
@@ -12,7 +11,7 @@ By default, filters that control components with [dynamic data](data.md#dynamic-
To add a filter to your page, do the following:
1. add the [`Filter`][vizro.models.Filter] model into the `controls` argument of the [`Page`][vizro.models.Page] model
-2. configure the `column` argument, which denotes the target column to be filtered
+1. configure the `column` argument, which denotes the target column to be filtered
You can also set `targets` to specify which components on the page the filter should apply to. If this is not explicitly set then `targets` defaults to all components on the page whose data source includes `column`.
@@ -39,6 +38,7 @@ You can also set `targets` to specify which components on the page the filter sh
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -57,17 +57,15 @@ You can also set `targets` to specify which components on the page the filter sh
type: filter
title: My first page
```
- === "Result"
- [![Filter]][Filter]
-
- [Filter]: ../../assets/user_guides/control/control1.png
+ === "Result"
+ [![Filter]][filter]
The selector is configured automatically based on the target column type data as follows:
- - Categorical data uses [`vm.Dropdown(multi=True)`][vizro.models.Dropdown] where `options` is the set of unique values found in `column` across all the data sources of components in `targets`.
- - [Numerical data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_numeric_dtype.html) uses [`vm.RangeSlider`][vizro.models.RangeSlider] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`.
- - [Temporal data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_datetime64_any_dtype.html) uses [`vm.DatePicker(range=True)`][vizro.models.DatePicker] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`. A column can be converted to this type with [pandas.to_datetime](https://pandas.pydata.org/docs/reference/api/pandas.to_datetime.html).
+- Categorical data uses [`vm.Dropdown(multi=True)`][vizro.models.Dropdown] where `options` is the set of unique values found in `column` across all the data sources of components in `targets`.
+- [Numerical data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_numeric_dtype.html) uses [`vm.RangeSlider`][vizro.models.RangeSlider] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`.
+- [Temporal data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_datetime64_any_dtype.html) uses [`vm.DatePicker(range=True)`][vizro.models.DatePicker] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`. A column can be converted to this type with [pandas.to_datetime](https://pandas.pydata.org/docs/reference/api/pandas.to_datetime.html).
The following example demonstrates these default selector types.
@@ -107,6 +105,7 @@ The following example demonstrates these default selector types.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -129,15 +128,13 @@ The following example demonstrates these default selector types.
type: filter
title: My first page
```
- === "Result"
- [![Filter]][Filter]
- [Filter]: ../../assets/user_guides/selectors/default_filter_selectors.png
+ === "Result"
+ [![Filter]][filter]
## Change selector
-If you want to have a different selector for your filter, you can give the `selector` argument of the [`Filter`][vizro.models.Filter] a different selector model.
-Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropdown`][vizro.models.Dropdown], [`RadioItems`][vizro.models.RadioItems], [`RangeSlider`][vizro.models.RangeSlider], [`Slider`][vizro.models.Slider], and [`DatePicker`][vizro.models.DatePicker].
+If you want to have a different selector for your filter, you can give the `selector` argument of the [`Filter`][vizro.models.Filter] a different selector model. Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropdown`][vizro.models.Dropdown], [`RadioItems`][vizro.models.RadioItems], [`RangeSlider`][vizro.models.RangeSlider], [`Slider`][vizro.models.Slider], and [`DatePicker`][vizro.models.DatePicker].
!!! example "Filter with different selector"
=== "app.py"
@@ -162,6 +159,7 @@ Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropd
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -181,11 +179,9 @@ Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropd
type: filter
title: My first page
```
- === "Result"
-
- [![Selector]][Selector]
- [Selector]: ../../assets/user_guides/control/control2.png
+ === "Result"
+ [![Selector]][selector]
## Further customization
@@ -220,6 +216,7 @@ Below is an advanced example where we only target one page component, and where
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -244,17 +241,19 @@ Below is an advanced example where we only target one page component, and where
controls:
- column: petal_length
targets:
- - scatter_chart
+ - scatter_chart
selector:
step: 1
type: range_slider
type: filter
title: My first page
```
- === "Result"
-
- [![Advanced]][Advanced]
- [Advanced]: ../../assets/user_guides/control/control3.png
+ === "Result"
+ [![Advanced]][advanced]
To further customize selectors, see our [how-to-guide on creating custom components](custom-components.md).
+
+[advanced]: ../../assets/user_guides/control/control3.png
+[filter]: ../../assets/user_guides/control/control1.png
+[selector]: ../../assets/user_guides/control/control2.png
diff --git a/vizro-core/docs/pages/user-guides/graph.md b/vizro-core/docs/pages/user-guides/graph.md
index 36c670997..1c3ffc8bc 100755
--- a/vizro-core/docs/pages/user-guides/graph.md
+++ b/vizro-core/docs/pages/user-guides/graph.md
@@ -6,25 +6,18 @@ The [`Graph`][vizro.models.Graph] model is the most used component in many dashb
To add a [`Graph`][vizro.models.Graph] to your page, do the following:
-1. insert the [`Graph`][vizro.models.Graph] model into the `components` argument of the
-[`Page`][vizro.models.Page] model
-2. enter any of the currently available charts of the open source library [`plotly.express`](https://plotly.com/python/plotly-express/) into the `figure` argument
+1. insert the [`Graph`][vizro.models.Graph] model into the `components` argument of the [`Page`][vizro.models.Page] model
+1. enter any of the currently available charts of the open source library [`plotly.express`](https://plotly.com/python/plotly-express/) into the `figure` argument
!!! note
+ To use the [`plotly.express`](https://plotly.com/python/plotly-express/) chart in a Vizro dashboard, you need to import it as `import vizro.plotly.express as px`. This leaves any of the [`plotly.express`](https://plotly.com/python/plotly-express/) functionality untouched yet enables _direct insertion_ into the [`Graph`][vizro.models.Graph] model _as is_.
- In order to use the [`plotly.express`](https://plotly.com/python/plotly-express/) chart in a Vizro dashboard, you need to import it as `import vizro.plotly.express as px`.
- This leaves any of the [`plotly.express`](https://plotly.com/python/plotly-express/) functionality untouched, but allows _direct insertion_ into the [`Graph`][vizro.models.Graph] model _as is_.
-
- Note also that the `plotly.express` chart needs to have a `data_frame` argument. In case you require a chart without
- a `data_frame` argument (for example, the [`imshow` chart](https://plotly.com/python/imshow/)), refer to our
- [guide on custom charts](custom-charts.md).
-
+ Note also that the `plotly.express` chart needs to have a `data_frame` argument. In case you require a chart without a `data_frame` argument (for example, the [`imshow` chart](https://plotly.com/python/imshow/)), refer to our [guide on custom charts](custom-charts.md).
## Insert Plotly chart
!!! example "Graph"
=== "app.py"
-
```{.python pycafe-link}
import vizro.models as vm
import vizro.plotly.express as px
@@ -47,25 +40,24 @@ To add a [`Graph`][vizro.models.Graph] to your page, do the following:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: scatter_matrix
- color: species
- data_frame: iris
- dimensions: ["sepal_length", "sepal_width", "petal_length", "petal_width"]
- type: graph
- title: My first page
+ - components:
+ - figure:
+ _target_: scatter_matrix
+ color: species
+ data_frame: iris
+ dimensions: [sepal_length, sepal_width, petal_length, petal_width]
+ type: graph
+ title: My first page
```
- === "Result"
- [![Graph]][Graph]
-
- [Graph]: ../../assets/user_guides/components/graph.png
+ === "Result"
+ [![Graph]][graph]
In the Python example we directly inserted the pandas DataFrame `df` into `figure=px.scatter_matrix(df, ...)`. This is [one way to supply data to a chart](data.md#supply-directly). For the YAML version, we [refer to the data source by name](data.md#reference-by-name) as `data_frame: iris`. For a full explanation of the different methods you can use to send data to your dashboard, see [our guide to using data in Vizro](data.md).
@@ -73,31 +65,24 @@ In the Python example we directly inserted the pandas DataFrame `df` into `figur
You will need to create a custom chart if you want to customize the Plotly chart beyond a function call, for example by:
-* using post-update methods like `update_layout`, `update_xaxes`, `update_traces`, or
-* by creating a custom `plotly.graph_objects.Figure()` object and manually adding traces with `add_trace`.
-
-For more details, refer to our [user guide on custom chart](custom-charts.md) and the
-[Plotly documentation on updating figures](https://plotly.com/python/creating-and-updating-figures/).
+- using post-update methods like `update_layout`, `update_xaxes`, `update_traces`, or
+- by creating a custom `plotly.graph_objects.Figure()` object and manually adding traces with `add_trace`.
+For more details, refer to our [user guide on custom chart](custom-charts.md) and the [Plotly documentation on updating figures](https://plotly.com/python/creating-and-updating-figures/).
## Add title, header, and footer
-The [`Graph`][vizro.models.Graph] accepts a `title`, `header` and `footer` argument. This is useful for providing
-context to the data being displayed, or for adding a description of the data.
+The [`Graph`][vizro.models.Graph] accepts a `title`, `header` and `footer` argument. This is useful for context on the data being displayed, or for adding a description of the data.
- **title**: Displayed as an [H3 header](https://dash.plotly.com/dash-html-components/h3), useful for summarizing the main topic or insight of the component.
- **header**: Accepts markdown text, ideal for extra descriptions, subtitles, or detailed data insights.
- **footer**: Accepts markdown text, commonly used for citing data sources, providing information on the last update, or adding disclaimers.
-
!!! note
-
- Although you can directly provide a `title` to the Plotly Express chart, we recommend using `Graph.title` for
- proper alignment with other components on the screen.
+ Although you can directly give a `title` to the Plotly Express chart, we recommend using `Graph.title` for proper alignment with other components on the screen.
!!! example "Formatted Graph"
=== "app.py"
-
```{.python pycafe-link}
import vizro.models as vm
@@ -126,31 +111,34 @@ context to the data being displayed, or for adding a description of the data.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: scatter
- x: sepal_width
- y: sepal_length
- color: species
- data_frame: iris
- title: Relationships between Sepal Width and Sepal Length
- header: |
- Each point in the scatter plot represents one of the 150 iris flowers, with colors indicating their
- types. The Setosa type is easily identifiable by its short and wide sepals.
-
- However, there is still overlap between the Versicolor and Virginica types when considering only sepal
- width and length.
- footer: |
- SOURCE: **Plotly iris data set, 2024**
- type: graph
- title: Formatted Graph
+ - components:
+ - figure:
+ _target_: scatter
+ x: sepal_width
+ y: sepal_length
+ color: species
+ data_frame: iris
+ title: Relationships between Sepal Width and Sepal Length
+ header: |
+ Each point in the scatter plot represents one of the 150 iris flowers, with colors indicating their
+ types. The Setosa type is easily identifiable by its short and wide sepals.
+
+ However, there is still overlap between the Versicolor and Virginica types when considering only sepal
+ width and length.
+ footer: |
+ SOURCE: **Plotly iris data set, 2024**
+ type: graph
+ title: Formatted Graph
```
+
=== "Result"
- [![FormattedGraph]][FormattedGraph]
+ [![FormattedGraph]][formattedgraph]
- [FormattedGraph]: ../../assets/user_guides/components/formatted_graph.png
+[formattedgraph]: ../../assets/user_guides/components/formatted_graph.png
+[graph]: ../../assets/user_guides/components/graph.png
diff --git a/vizro-core/docs/pages/user-guides/install.md b/vizro-core/docs/pages/user-guides/install.md
index 4d4c01239..6a07911e5 100644
--- a/vizro-core/docs/pages/user-guides/install.md
+++ b/vizro-core/docs/pages/user-guides/install.md
@@ -8,8 +8,8 @@ We recommend that you create a virtual environment for each Vizro project you wo
## Prerequisites to working locally
-* **Python**: Vizro supports macOS, Linux, and Windows. It works with Python 3.9 and later.
-* **Virtual environment**: You specify the version of Python to use with Vizro when you set up the virtual environment. See the following references to learn more about [Python virtual environments](https://realpython.com/python-virtual-environments-a-primer/), [Conda virtual environments](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#starting-conda) or [watch an explainer video about them](https://youtu.be/YKfAwIItO7M).
+- **Python**: Vizro supports macOS, Linux, and Windows. It works with Python 3.9 and later.
+- **Virtual environment**: You specify the version of Python to use with Vizro when you set up the virtual environment. See the following references to learn more about [Python virtual environments](https://realpython.com/python-virtual-environments-a-primer/), [Conda virtual environments](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#starting-conda) or [watch an explainer video about them](https://youtu.be/YKfAwIItO7M).
### How to create a virtual environment for your Vizro project
diff --git a/vizro-core/docs/pages/user-guides/kedro-data-catalog.md b/vizro-core/docs/pages/user-guides/kedro-data-catalog.md
index 0e2b0954e..ce4b060fa 100644
--- a/vizro-core/docs/pages/user-guides/kedro-data-catalog.md
+++ b/vizro-core/docs/pages/user-guides/kedro-data-catalog.md
@@ -3,6 +3,7 @@
This page describes how to integrate Vizro with [Kedro](https://docs.kedro.org/en/stable/index.html), an open-source Python framework to create reproducible, maintainable, and modular data science code. For Pandas datasets registered in a Kedro data catalog, Vizro provides a convenient way to visualize them.
## Installation
+
If you already have Kedro installed then you do not need to install any extra dependencies. If you do not have Kedro installed then you should run:
```bash
@@ -10,7 +11,9 @@ pip install vizro[kedro]
```
## Use datasets from the Kedro Data Catalog
+
`vizro.integrations.kedro` provides functions to help generate and process a [Kedro Data Catalog](https://docs.kedro.org/en/stable/data/index.html). Given a Kedro Data Catalog `catalog`, the general pattern to add datasets into the Vizro data manager is:
+
```python
from vizro.integrations import kedro as kedro_integration
from vizro.managers import data_manager
@@ -25,15 +28,14 @@ This imports all datasets of type [`kedro_datasets.pandas`](https://docs.kedro.o
The `catalog` variable may have been created in a number of different ways:
1. Kedro project path. Vizro exposes a helper function `vizro.integrations.kedro.catalog_from_project` to generate a `catalog` given the path to a Kedro project.
-2. [Kedro Jupyter session](https://docs.kedro.org/en/stable/notebooks_and_ipython/kedro_and_notebooks.html). This automatically exposes `catalog`.
-3. Data Catalog configuration file (`catalog.yaml`). This can create a `catalog` entirely independently of a Kedro project using [`kedro.io.DataCatalog.from_config`](https://docs.kedro.org/en/stable/kedro.io.DataCatalog.html#kedro.io.DataCatalog.from_config).
+1. [Kedro Jupyter session](https://docs.kedro.org/en/stable/notebooks_and_ipython/kedro_and_notebooks.html). This automatically exposes `catalog`.
+1. Data Catalog configuration file (`catalog.yaml`). This can create a `catalog` entirely independently of a Kedro project using [`kedro.io.DataCatalog.from_config`](https://docs.kedro.org/en/stable/kedro.io.DataCatalog.html#kedro.io.DataCatalog.from_config).
The full code for these different cases is given below.
!!! example "Import a Kedro Data Catalog into the Vizro data manager"
-
=== "app.py (Kedro project path)"
- ```py
+ ```python
from vizro.integrations import kedro as kedro_integration
from vizro.managers import data_manager
@@ -43,16 +45,18 @@ The full code for these different cases is given below.
for dataset_name, dataset in kedro_integration.datasets_from_catalog(catalog).items():
data_manager[dataset_name] = dataset
```
+
=== "app.ipynb (Kedro Jupyter session)"
- ```py
+ ```python
from vizro.managers import data_manager
for dataset_name, dataset in kedro_integration.datasets_from_catalog(catalog).items():
data_manager[dataset_name] = dataset
```
+
=== "app.py (Data Catalog configuration file)"
- ```py
+ ```python
from kedro.io import DataCatalog
import yaml
diff --git a/vizro-core/docs/pages/user-guides/layouts.md b/vizro-core/docs/pages/user-guides/layouts.md
index 8361560db..af66ec301 100644
--- a/vizro-core/docs/pages/user-guides/layouts.md
+++ b/vizro-core/docs/pages/user-guides/layouts.md
@@ -3,11 +3,10 @@
The [`Page`][vizro.models.Page] model accepts a `layout` argument that enables custom arrangement of charts and components on the screen. This guide shows how to customize the grid specifications in the [`Layout`][vizro.models.Layout].
## The default layout
-The `layout` argument of the [`Page`][vizro.models.Page] model is optional. If no layout is specified, all charts/components are automatically [**stacked vertically**](layouts.md#vertical-and-horizontal-stacking) on the page in one column.
-If you are happy with that arrangement, you can create your charts/components without providing a [`Layout`][vizro.models.Layout].
-!!! example "Default Layout"
+The `layout` argument of the [`Page`][vizro.models.Page] model is optional. If no layout is specified, all charts/components are automatically [**stacked vertically**](layouts.md#vertical-and-horizontal-stacking) on the page in one column. If you are happy with that arrangement, you can create your charts/components without providing a [`Layout`][vizro.models.Layout].
+!!! example "Default Layout"
=== "app.py"
```{.python pycafe-link}
from vizro import Vizro
@@ -23,35 +22,33 @@ If you are happy with that arrangement, you can create your charts/components wi
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- title: two_left
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ title: two_left
```
- === "Result"
- [![Layout]][Layout]
-
- [Layout]: ../../assets/user_guides/layout/two_left.png
-
+ === "Result"
+ [![Layout]][layout]
## Configure the grid
+
To customize the grid arrangement, configure the `grid` parameter of the [`Layout`][vizro.models.Layout] model.
The example below shows an example of a valid `grid`:
```python title="Basic example"
-grid = [[0, 1],
- [0, 2]]
+grid = [[0, 1], [0, 2]]
```
- The `grid` must be provided as `list[list[int]]` (for example, `grid = [[0, 1], [0, 2]]`).
@@ -64,16 +61,12 @@ grid = [[0, 1],
- The area spanned by a chart/component in the grid must be rectangular.
- The grid can be arbitrarily large, allowing arbitrarily granular control of the grid.
-
## Vertical and horizontal stacking
+
As described above, when no `Layout` is specified, components are presented **vertically** as a single-column stack. If you have three components, the default `Layout.grid` will be as follows, with three equally sized rows, each containing a component spanning the entire width:
```python title="Vertical stacking"
-grid = [
- [0],
- [1],
- [2]
- ]
+grid = [[0], [1], [2]]
```
To present components **horizontally** in one row:
@@ -89,8 +82,8 @@ This defines a single row that occupies the entire width and height, divided int
## Grid - basic example
-!!! example "Grid Arrangement - Basic Example"
+!!! example "Grid Arrangement - Basic Example"
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -109,39 +102,37 @@ This defines a single row that occupies the entire width and height, divided int
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- - text: |
- # Component 2
- type: card
- layout:
- grid: [[0, 1], [0, 2]]
- title: one_left_two_right
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ layout:
+ grid: [[0, 1], [0, 2]]
+ title: one_left_two_right
```
- === "Result"
- [![Grid]][Grid]
- [Grid]: ../../assets/user_guides/layout/one_left_two_right.png
+ === "Result"
+ [![Grid]][grid]
## Grid - advanced example
If you want to divide the grid into subgrids with finer control over these, you can use [`Containers`](container.md). See our section on [when to use `Containers` vs. `Page.layout`](container.md#when-to-use-containers) for more information.
-The `Layout` provides full control over the arrangement of top-level components within a page,
-allowing arbitrarily granular control of the grid by creating larger grids.
+The `Layout` provides full control over the arrangement of top-level components within a page, allowing arbitrarily granular control of the grid by creating larger grids.
!!! example "Grid Arrangement - Advanced Example"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -208,6 +199,7 @@ allowing arbitrarily granular control of the grid by creating larger grids.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -260,44 +252,44 @@ allowing arbitrarily granular control of the grid by creating larger grids.
grid: [[0, 1, 3, 4], [2, 2, 3, 4]]
title: Custom Layout - Advanced Example
```
- === "Result"
- [![GridAdv]][GridAdv]
- [GridAdv]: ../../assets/user_guides/layout/grid_advanced.png
+ === "Result"
+ [![GridAdv]][gridadv]
## Custom layout examples
+
Here is a reference table of example layouts:
+
one row with one component, second row with two components stacked horizontally
-| Layout needed | Grid | Code |
-|--------------------------------|----------------------------|-------------------------------------------------------------------------------------|
-| | | `layout=vm.Layout(grid=[[0]])` |
-| | | `layout=vm.Layout(grid=[[0],[1]])` |
-| | | `layout=vm.Layout(grid=[[0,1]])` |
-| | | `layout=vm.Layout(grid=[[0],[1],[2]])` or
`layout=None` |
-| | | `layout=vm.Layout(grid=[[0,1],[0,2]])` |
-| | | `layout=vm.Layout(grid=[[0,0],[1,2]])` |
-| | | `layout=vm.Layout(grid=[[0,1],[2,2]])` |
-| | | `layout=vm.Layout(grid=[[0,1],[0,2],[0,3]])` |
-| | | `layout=vm.Layout(grid=[[0,1],[2,3]])` |
-| | | `layout=vm.Layout(grid=[[0,3],[1,3],[2,3]])` |
-| | | `layout=vm.Layout(grid=[[0,0,0],[1,2,3]])` |
-| | | `layout=vm.Layout(grid=[[0,1,2],[3,3,3]])` |
+| Layout needed | Grid | Code |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| | | `layout=vm.Layout(grid=[[0]])` |
+| | | `layout=vm.Layout(grid=[[0],[1]])` |
+| | | `layout=vm.Layout(grid=[[0,1]])` |
+| | | `layout=vm.Layout(grid=[[0],[1],[2]])` or
`layout=None` |
+| | | `layout=vm.Layout(grid=[[0,1],[0,2]])` |
+| | | `layout=vm.Layout(grid=[[0,0],[1,2]])` |
+| | | `layout=vm.Layout(grid=[[0,1],[2,2]])` |
+| | | `layout=vm.Layout(grid=[[0,1],[0,2],[0,3]])` |
+| | | `layout=vm.Layout(grid=[[0,1],[2,3]])` |
+| | | `layout=vm.Layout(grid=[[0,3],[1,3],[2,3]])` |
+| | | `layout=vm.Layout(grid=[[0,0,0],[1,2,3]])` |
+| | | `layout=vm.Layout(grid=[[0,1,2],[3,3,3]])` |
## Add empty sections to the grid
+
One approach to organize the dashboard's layout involves integrating empty sections by specifying `-1` within the grid layout.
```python title="Example"
-grid = [[0, 1, -1],
- [0, 2, -1]]
+grid = [[0, 1, -1], [0, 2, -1]]
```
!!! example "Adding Empty Spaces"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -316,38 +308,38 @@ grid = [[0, 1, -1],
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- - text: |
- # Component 2
- type: card
- layout:
- grid: [[0, 1, -1], [0, 2, -1]]
- title: Adding empty spaces
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ layout:
+ grid: [[0, 1, -1], [0, 2, -1]]
+ title: Adding empty spaces
```
- === "Result"
- [![GridEmpty]][GridEmpty]
- [GridEmpty]: ../../assets/user_guides/layout/layout_empty_spaces.png
+ === "Result"
+ [![GridEmpty]][gridempty]
## Control the scroll behavior
+
By default, the grid fits all charts/components on the screen. This can lead to distortions such that the chart/component looks squashed. To control the scroll behavior, you can specify the following:
- `row_min_height`: Sets a chart/component's minimum height. Defaults to 0px.
- `col_min_width`: Sets a chart/component's minimum width. Defaults to 0px.
!!! example "Activate Scrolling"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -371,59 +363,63 @@ By default, the grid fits all charts/components on the screen. This can lead to
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- - text: |
- # Component 2
- type: card
- - text: |
- # Component 2
- type: card
- - text: |
- # Component 4
- type: card
- - text: |
- # Component 5
- type: card
- - text: |
- # Component 6
- type: card
- - text: |
- # Component 7
- type: card
- layout:
- grid: [[0], [1], [2], [3], [4], [5], [6], [7]]
- row_min_height: 240px
- title: Activate scrolling
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ - text: |
+ # Component 4
+ type: card
+ - text: |
+ # Component 5
+ type: card
+ - text: |
+ # Component 6
+ type: card
+ - text: |
+ # Component 7
+ type: card
+ layout:
+ grid: [[0], [1], [2], [3], [4], [5], [6], [7]]
+ row_min_height: 240px
+ title: Activate scrolling
```
- === "Result"
- [![GridScroll]][GridScroll]
-
- [GridScroll]: ../../assets/user_guides/layout/grid_scroll.png
+ === "Result"
+ [![GridScroll]][gridscroll]
## Further customization
-For further customization, such as changing the gap between row and column, refer to the
-documentation of the [`Layout`][vizro.models.Layout] model.
+
+For further customization, such as changing the gap between row and column, refer to the documentation of the [`Layout`][vizro.models.Layout] model.
## Alternative layout approaches
+
In general, any arbitrarily granular layout can already be achieved using [`Page.layout`](layouts.md) alone and is our recommended approach if you want to arrange components on a page with consistent row and/or column spacing.
!!! note "Alternative layout approaches: `Tabs` and `Containers`"
-
- [`Tabs`][vizro.models.Tabs] and [`Containers`][vizro.models.Container] provide an alternative approach to customize your page layout.
- For example, if you want to have more granular control and break the overall page grid into subgrids, see our [user guide on Containers](container.md).
+ [`Tabs`][vizro.models.Tabs] and [`Containers`][vizro.models.Container] offer an alternative approach to customize your page layout. For example, if you want to have more granular control and break the overall page grid into subgrids, see our [user guide on Containers](container.md).
If you want to display multiple containers on one page by putting them into the same screen space, and letting the user switch between them, see our [user guide on Tabs](tabs.md).
{ width="500" }
+
+[grid]: ../../assets/user_guides/layout/one_left_two_right.png
+[gridadv]: ../../assets/user_guides/layout/grid_advanced.png
+[gridempty]: ../../assets/user_guides/layout/layout_empty_spaces.png
+[gridscroll]: ../../assets/user_guides/layout/grid_scroll.png
+[layout]: ../../assets/user_guides/layout/two_left.png
diff --git a/vizro-core/docs/pages/user-guides/navigation.md b/vizro-core/docs/pages/user-guides/navigation.md
index 41c6bb9dc..75a661470 100644
--- a/vizro-core/docs/pages/user-guides/navigation.md
+++ b/vizro-core/docs/pages/user-guides/navigation.md
@@ -2,8 +2,7 @@
This guide shows you how to use and customize the navigation that appears on the left of your dashboard.
-The [`Dashboard`][vizro.models.Dashboard] model accepts a `navigation` argument, where you can enter a [`Navigation`][vizro.models.Navigation] model. This enables you to group pages together and customize how they appear in your navigation.
-The dashboard includes a collapsible side panel that users can minimize or expand by a button click. The collapse button, located in the top right corner of the side panel, is visible by default for user convenience.
+The [`Dashboard`][vizro.models.Dashboard] model accepts a `navigation` argument, where you can enter a [`Navigation`][vizro.models.Navigation] model. This enables you to group pages together and customize how they appear in your navigation. The dashboard includes a collapsible side panel that users can minimize or expand by a button click. The collapse button, located in the top right corner of the side panel, is visible by default for user convenience.
## Use the default navigation
@@ -56,8 +55,8 @@ By default, if the `navigation` argument is not specified, Vizro creates a navig
type: graph
title: My first page
- components:
- - text: My text here
- type: card
+ - text: My text here
+ type: card
title: My second page
- components:
- figure:
@@ -69,10 +68,9 @@ By default, if the `navigation` argument is not specified, Vizro creates a navig
type: graph
title: My third page
```
- === "Result"
- [![DefaultNavigation]][DefaultNavigation]
- [DefaultNavigation]: ../../assets/user_guides/navigation/default_navigation.png
+ === "Result"
+ [![DefaultNavigation]][defaultnavigation]
## Include a subset of pages
@@ -132,17 +130,15 @@ To include only some of your dashboard pages in your navigation then list them i
- My first page
- My second page
```
- === "Result"
- [![OnlySomePages]][OnlySomePages]
- [OnlySomePages]: ../../assets/user_guides/navigation/only_some_pages.png
+ === "Result"
+ [![OnlySomePages]][onlysomepages]
## Group pages
You can also group your pages together by specifying `pages` as a dictionary:
!!! example "Grouping pages"
-
=== "snippet.py"
```py
# page_1, page_2, page_3 defined as in default example
@@ -154,7 +150,6 @@ You can also group your pages together by specifying `pages` as a dictionary:
```
=== "app.py"
-
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -187,6 +182,7 @@ You can also group your pages together by specifying `pages` as a dictionary:
)
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -200,18 +196,15 @@ You can also group your pages together by specifying `pages` as a dictionary:
Group B:
- My third page
```
- === "Result"
- [![GroupedNavigation]][GroupedNavigation]
-
- [GroupedNavigation]: ../../assets/user_guides/navigation/grouped_navigation.png
+ === "Result"
+ [![GroupedNavigation]][groupednavigation]
## Use a navigation bar with icons
Another way to group together pages in the navigation is to use a [`NavBar`][vizro.models.NavBar] with icons. The simplest way to use this is to change the `nav_selector` specified in [`Navigation`][vizro.models.Navigation]:
!!! example "Using `NavBar`"
-
=== "snippet.py"
```py
# page_1, page_2, page_3 defined as in default example
@@ -223,8 +216,8 @@ Another way to group together pages in the navigation is to use a [`NavBar`][viz
)
Vizro().build(dashboard).run()
```
- === "app.py"
+ === "app.py"
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -276,14 +269,11 @@ Another way to group together pages in the navigation is to use a [`NavBar`][viz
nav_selector:
type: nav_bar
```
- === "Result"
- [![NavBar]][NavBar]
-
- [NavBar]: ../../assets/user_guides/navigation/nav_bar.png
+ === "Result"
+ [![NavBar]][navbar]
-Here, the first level of the navigation hierarchy ("Group A" and "Group B") is represented by an icon in a navigation bar, and the second level of the navigation (the pages) is represented by an accordion.
-By default, the set of icons used are the [`filter` icons from the Google Material icons library](https://fonts.google.com/icons?icon.query=filter). The icon label ("Group A" and "Group B") appears as a tooltip on hovering over the icon.
+Here, the first level of the navigation hierarchy ("Group A" and "Group B") is represented by an icon in a navigation bar, and the second level of the navigation (the pages) is represented by an accordion. By default, the set of icons used are the [`filter` icons from the Google Material icons library](https://fonts.google.com/icons?icon.query=filter). The icon label ("Group A" and "Group B") appears as a tooltip on hovering over the icon.
## Customize the navigation bar
@@ -314,7 +304,6 @@ The same configuration for [grouping pages](#group-pages) applies inside a `NavL
```
=== "app.py"
-
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -375,10 +364,9 @@ The same configuration for [grouping pages](#group-pages) applies inside a `NavL
Group B:
- My third page
```
- === "Result"
- [![AccordionInsideNavBar]][AccordionInsideNavBar]
- [AccordionInsideNavBar]: ../../assets/user_guides/navigation/accordion_inside_nav_bar.png
+ === "Result"
+ [![AccordionInsideNavBar]][accordioninsidenavbar]
You can alter the icons used by specifying the name of the icon in the [Google Material icons library](https://fonts.google.com/icons):
@@ -402,8 +390,8 @@ You can alter the icons used by specifying the name of the icon in the [Google M
),
)
```
- === "app.py"
+ === "app.py"
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -468,7 +456,13 @@ You can alter the icons used by specifying the name of the icon in the [Google M
pages:
- My third page
```
- === "Result"
- [![CustomIcons]][CustomIcons]
- [CustomIcons]: ../../assets/user_guides/navigation/custom_icons.png
+ === "Result"
+ [![CustomIcons]][customicons]
+
+[accordioninsidenavbar]: ../../assets/user_guides/navigation/accordion_inside_nav_bar.png
+[customicons]: ../../assets/user_guides/navigation/custom_icons.png
+[defaultnavigation]: ../../assets/user_guides/navigation/default_navigation.png
+[groupednavigation]: ../../assets/user_guides/navigation/grouped_navigation.png
+[navbar]: ../../assets/user_guides/navigation/nav_bar.png
+[onlysomepages]: ../../assets/user_guides/navigation/only_some_pages.png
diff --git a/vizro-core/docs/pages/user-guides/pages.md b/vizro-core/docs/pages/user-guides/pages.md
index 7ae944e9b..71e01e9f9 100644
--- a/vizro-core/docs/pages/user-guides/pages.md
+++ b/vizro-core/docs/pages/user-guides/pages.md
@@ -1,7 +1,6 @@
# How to use pages
-This guide shows you how to add pages to your dashboard and customize the URL paths if needed.
-A [`Page`][vizro.models.Page] lets you place and arrange your dashboard content (for example, chart/components, tables, and text)
-and configure your dashboard interactions (such as filters and parameters).
+
+This guide shows you how to add pages to your dashboard and customize the URL paths if needed. A [`Page`][vizro.models.Page] lets you place and arrange your dashboard content (for example, chart/components, tables, and text) and configure your dashboard interactions (such as filters and parameters).
The [`Dashboard`][vizro.models.Dashboard] model accepts the `pages` argument, where you can insert your [`Page`][vizro.models.Page].
@@ -10,19 +9,19 @@ The [`Dashboard`][vizro.models.Dashboard] model accepts the `pages` argument, wh
A [`Page`][vizro.models.Page] is split up into four main containers:
1. The **navigation container** where you can customize your `navigation` (see [Dashboard](dashboard.md) and [Navigation](navigation.md) for more information). Note that the navigation container needs to be configured via the Dashboard.
-2. The **control container** where you can add your `controls` (see [Filters](filters.md) or [Parameters](parameters.md)) to interact with the dashboard
-3. The **page header** that contains the page title and the theme toggle switch button
-4. The **component container** where you can add your [components](components.md) to visualize your data
+1. The **control container** where you can add your `controls` (see [Filters](filters.md) or [Parameters](parameters.md)) to interact with the dashboard
+1. The **page header** that contains the page title and the theme toggle switch button
+1. The **component container** where you can add your [components](components.md) to visualize your data
To create and add a page to your dashboard, do the following steps:
1. Set a `title` for your [`Page`][vizro.models.Page]
-2. Configure your `components`, see our guide on the [various options](components.md)
-3. (optional) Configure your `controls` , see our guides on [Filters](filters.md) and [Parameters](parameters.md)
-4. (optional) Configure your `layout` , see our guide on [Layouts](layouts.md)
-5. (optional) Give a `description` of your `Page` to the app's [meta tags](https://metatags.io/)
+1. Configure your `components`, see our guide on the [various options](components.md)
+1. (optional) Configure your `controls` , see our guides on [Filters](filters.md) and [Parameters](parameters.md)
+1. (optional) Configure your `layout` , see our guide on [Layouts](layouts.md)
+1. (optional) Give a `description` of your `Page` to the app's [meta tags](https://metatags.io/)
!!! example "Page"
=== "app.py"
@@ -51,51 +50,47 @@ To create and add a page to your dashboard, do the following steps:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: sunburst
- path: ['continent', 'country']
- values: pop
- color: lifeExp
- data_frame: gapminder
- id: sunburst
- type: graph
- controls:
- - column: continent
- targets:
- - sunburst
- type: filter
- - selector:
- options: ['lifeExp', 'pop']
- title: Color
- type: radio_items
- targets:
- - sunburst.color
- type: parameter
- title: Page Title
- description: "Longer description of the page content"
+ - components:
+ - figure:
+ _target_: sunburst
+ path: [continent, country]
+ values: pop
+ color: lifeExp
+ data_frame: gapminder
+ id: sunburst
+ type: graph
+ controls:
+ - column: continent
+ targets: [sunburst]
+ type: filter
+ - selector:
+ options: [lifeExp, pop]
+ title: Color
+ type: radio_items
+ targets: [sunburst.color]
+ type: parameter
+ title: Page Title
+ description: Longer description of the page content
```
- === "Result"
- [![Page]][Page]
- [Page]: ../../assets/user_guides/pages/page_sunburst.png
+ === "Result"
+ [![Page]][page]
An accordion page selector is automatically added to your dashboard in the top-left of the control container for through the different pages. It will not be added if your dashboard consists of only one page.
You can additionally navigate through the different pages by going directly to the relevant page URL (more details in next section).
-
## Customize the page URL
-By default, the page URL is automatically generated based on the `id` of the page. For example, if `id="This is my first page"`
-the generated page URL will be `path=this-is-my-first-page`. You can then access the page via `localhost:/this-is-my-first-page`.
-Note that the page `id` defaults to be the same as the page `title` if not set.
-If you have multiple pages with the same `title` then you must assign a unique `id`.
+By default, the page URL is automatically generated based on the `id` of the page. For example, if `id="This is my first page"` the generated page URL will be `path=this-is-my-first-page`. You can then access the page via `localhost:/this-is-my-first-page`.
+
+Note that the page `id` defaults to be the same as the page `title` if not set. If you have multiple pages with the same `title` then you must assign a unique `id`.
The first page always has the URL prefix `/` assigned. A custom URL can, therefore, not be created for the first page.
@@ -137,39 +132,40 @@ To customize the page URL, pass a valid URL name to the `path` argument of [`Pag
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- Commodi repudiandae consequuntur voluptatum.
- type: card
- title: Page 1
- - components:
- - figure:
- _target_: sunburst
- path: ['continent', 'country']
- values: pop
- color: lifeExp
- data_frame: gapminder
- id: sunburst
- type: graph
- controls:
- - column: continent
- targets:
- - sunburst
- type: filter
- - selector:
- options: ['lifeExp', 'pop']
- title: Color
- type: radio_items
- targets:
- - sunburst.color
- type: parameter
- title: Page 2
- path: my-custom-url
+ - components:
+ - text: |
+ Commodi repudiandae consequuntur voluptatum.
+ type: card
+ title: Page 1
+ - components:
+ - figure:
+ _target_: sunburst
+ path: [continent, country]
+ values: pop
+ color: lifeExp
+ data_frame: gapminder
+ id: sunburst
+ type: graph
+ controls:
+ - column: continent
+ targets: [sunburst]
+ type: filter
+ - selector:
+ options: [lifeExp, pop]
+ title: Color
+ type: radio_items
+ targets: [sunburst.color]
+ type: parameter
+ title: Page 2
+ path: my-custom-url
```
You can now access the first page via `localhost:/` and the second page via `localhost:/my-custom-url`.
+
+[page]: ../../assets/user_guides/pages/page_sunburst.png
diff --git a/vizro-core/docs/pages/user-guides/parameters.md b/vizro-core/docs/pages/user-guides/parameters.md
index bb39a7a0c..c82707d4a 100644
--- a/vizro-core/docs/pages/user-guides/parameters.md
+++ b/vizro-core/docs/pages/user-guides/parameters.md
@@ -9,8 +9,8 @@ The [`Page`][vizro.models.Page] model accepts the `controls` argument, where you
To add a parameter to your page, do the following:
1. add the [`Parameter`][vizro.models.Parameter] model into the `controls` argument of the [`Page`][vizro.models.Page] model.
-2. add the `targets` argument
-3. add a selector model to the `selector` argument.
+1. add the `targets` argument
+1. add a selector model to the `selector` argument.
In the `targets` argument, you can specify the component and function argument that the parameter should be applied to in the form of `.` (for example, `scatter_chart.title`).
@@ -48,6 +48,7 @@ Unlike for the [`Filter`][vizro.models.Filter] model, you also have to configure
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -64,18 +65,17 @@ Unlike for the [`Filter`][vizro.models.Filter] model, you also have to configure
type: graph
controls:
- selector:
- options: ["My scatter chart", "A better title!", "Another title..."]
- multi: False
+ options: [My scatter chart, A better title!, Another title...]
+ multi: false
type: dropdown
targets:
- scatter_chart.title
type: parameter
title: My first page
```
- === "Result"
- [![Parameter]][Parameter]
- [Parameter]: ../../assets/user_guides/control/control4.png
+ === "Result"
+ [![Parameter]][parameter]
If you would like to pass `None` as a parameter and make a parameter optional, you can specify the string `"NONE"` in the `options` or `value` field.
@@ -133,6 +133,7 @@ If you want to change nested parameters, you can specify the `targets` argument
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -146,7 +147,7 @@ If you want to change nested parameters, you can specify the `targets` argument
y: sepal_length
size: petal_length
color: species
- color_discrete_map: {"setosa": "#00b4ff", "versicolor": "#ff9222"}
+ color_discrete_map: {setosa: '#00b4ff', versicolor: '#ff9222'}
id: scatter_chart
type: graph
- figure:
@@ -155,23 +156,22 @@ If you want to change nested parameters, you can specify the `targets` argument
x: sepal_width
y: sepal_length
color: species
- color_discrete_map: {"setosa": "#00b4ff", "versicolor": "#ff9222"}
+ color_discrete_map: {setosa: '#00b4ff', versicolor: '#ff9222'}
id: bar_chart
type: graph
controls:
- selector:
- options: ["#ff5267", "#3949ab"]
+ options: ['#ff5267', '#3949ab']
value: #3949ab
- multi: False
+ multi: false
type: dropdown
- targets: ["scatter_chart.color_discrete_map.virginica", "bar_chart.color_discrete_map.virginica"]
+ targets: [scatter_chart.color_discrete_map.virginica, bar_chart.color_discrete_map.virginica]
type: parameter
title: My first page
```
- === "Result"
- [![Nested]][Nested]
- [Nested]: ../../assets/user_guides/control/control5.png
+ === "Result"
+ [![Nested]][nested]
In the above example, the object passed to the function argument `color_discrete_map` is a dictionary which maps the different flower species to fixed colors (for example, `{"virginica":"blue"}`). In this case, only the value `blue` should be changed instead of the entire dictionary. This can be achieved by specifying a target as `scatter.color_discrete_map.virginica`.
@@ -180,3 +180,6 @@ Note that in the above example, one parameter affects multiple targets.
## Dynamic data parameters
If you use [dynamic data](data.md/#dynamic-data) that can be updated while the dashboard is running then you can pass parameters to the dynamic data function to alter the data loaded into your dashboard. For detailed instructions, refer to the section on [parametrized data loading](data.md/#parametrize-data-loading).
+
+[nested]: ../../assets/user_guides/control/control5.png
+[parameter]: ../../assets/user_guides/control/control4.png
diff --git a/vizro-core/docs/pages/user-guides/run.md b/vizro-core/docs/pages/user-guides/run.md
index df52e8c14..028eb5027 100644
--- a/vizro-core/docs/pages/user-guides/run.md
+++ b/vizro-core/docs/pages/user-guides/run.md
@@ -15,7 +15,6 @@ Most of our examples have a link below the code, [Run and edit this code in PyCa
You can use [PyCafe](https://py.cafe/snippet/vizro/v1) snippet mode to experiment with your own Vizro dashboards by dropping code into a new project.
-
## Default built-in Flask development server
!!! example "Default built-in Flask development server"
@@ -38,9 +37,10 @@ You can use [PyCafe](https://py.cafe/snippet/vizro/v1) snippet mode to experimen
Vizro().build(dashboard).run()
```
+
1. create a Python file named `app.py`.
-2. type the command `python app.py` into your terminal.
-3. information below will be displayed in your terminal, go to [http://127.0.0.1:8050/](http://127.0.0.1:8050/).
+1. type the command `python app.py` into your terminal.
+1. information below will be displayed in your terminal, go to [http://127.0.0.1:8050/](http://127.0.0.1:8050/).
```
Dash is running on http://127.0.0.1:8050/
@@ -51,8 +51,7 @@ INFO:werkzeug:WARNING: This is a development server. Do not use it in a producti
```
!!! warning "In production"
-
- As per the above warning message, which is [further explained in the Flask documentation](https://flask.palletsprojects.com/en/3.0.x/deploying/), the Flask development server is intended for use only during local development and **should not** be used when deploying to production. Instead, you should instead use a production-ready solution such as [Gunicorn](#gunicorn).
+ The above warning message is [further explained in the Flask documentation](https://flask.palletsprojects.com/en/3.0.x/deploying/). The Flask development server is intended for use only during local development and **should not** be used when deploying to production. Instead, you should instead use a production-ready solution such as [Gunicorn](#gunicorn).
### Automatic reloading and debugging
@@ -64,11 +63,11 @@ Setting `debug=True` enables [Dash Dev Tools](https://dash.plotly.com/devtools).
In addition, some errors generated at run time can also be viewed via the browser console (for example in `Chrome` see `View > Developer > Developer Tools > Console`).
-
## Jupyter
+
The dashboard application can be launched in a Jupyter environment in `inline`, `external`, and `jupyterlab` mode.
-!!! example "Run in a Jupyter Notebook in inline mode"
+!!! example "Run in a Jupyter Notebook in inline mode"
=== "app.ipynb"
```py linenums="1"
from vizro import Vizro
@@ -87,16 +86,16 @@ The dashboard application can be launched in a Jupyter environment in `inline`,
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run(jupyter_mode="external")
```
+
- by default, the mode is set to `inline` in `run()` and the dashboard will be displayed inside your Jupyter environment.
- you can specify `jupyter_mode="external"` and a link will be displayed to direct you to the localhost where the dashboard is running.
- you can use tab mode by `jupyter_mode="tab"` to automatically open the app in a new browser
!!! note "Reloading and debugging"
-
Code reloading and hot reloading do not work within a Jupyter Notebook. Instead, there are two methods to reload the dashboard:
- * Restart the Jupyter kernel and re-run your notebook.
- * Add a cell containing `from vizro import Vizro; Vizro._reset()` to the top of your notebook and re-run it. With this method, there is no need to restart the Jupyter kernel.
+ - Restart the Jupyter kernel and re-run your notebook.
+ - Add a cell containing `from vizro import Vizro; Vizro._reset()` to the top of your notebook and re-run it. With this method, there is no need to restart the Jupyter kernel.
## Gunicorn
@@ -126,17 +125,18 @@ The dashboard application can be launched in a Jupyter environment in `inline`,
```
1. The Vizro `app` object is a WSGI application that exposes the underlying Flask app; this will be used by Gunicorn.
- 2. Enable the same app to still be run using the built-in Flask server with `python app.py` for development purposes.
+ 1. Enable the same app to still be run using the built-in Flask server with `python app.py` for development purposes.
To run using Gunicorn with four worker processes, execute
+
```bash
gunicorn app:app --workers 4
```
+
in the command line. For more Gunicorn configuration options, refer to [Gunicorn documentation](https://docs.gunicorn.org/).
!!! warning "In production"
-
- If your dashboard uses [dynamic data](data.md#dynamic-data) that can be refreshed while the dashboard is running then you should [configure your data manager cache](data.md#configure-cache) to use a backend that supports multiple processes.
+ If your dashboard uses [dynamic data](data.md#dynamic-data) that can be refreshed while the dashboard is running then you should [configure your data manager cache](data.md#configure-cache) to use a back end that supports multiple processes.
## Deployment
@@ -149,6 +149,6 @@ Internally, `app = Vizro()` contains a Flask app in `app.dash.server`. However,
[`Vizro`][vizro.Vizro] accepts `**kwargs` that are passed through to `Dash`. This enables you to configure the underlying Dash app using the same [arguments that are available](https://dash.plotly.com/reference#dash.dash) in `Dash`. For example, in a deployment context, these arguments may be useful:
-- `url_base_pathname`: serve your Vizro app at a specific path rather than at the domain root. For example, if you host your dashboard at http://www.example.com/my_dashboard/ then you would set `url_base_pathname="/my_dashboard/"` or an environment variable `DASH_URL_BASE_PATHNAME="/my_dashboard/"`.
+- `url_base_pathname`: serve your Vizro app at a specific path rather than at the domain root. For example, if you host your dashboard at `http://www.example.com/my_dashboard/` then you would set `url_base_pathname="/my_dashboard/"` or an environment variable `DASH_URL_BASE_PATHNAME="/my_dashboard/"`.
- `serve_locally`: set to `False` to [serve Dash component libraries from a Content Delivery Network (CDN)](https://dash.plotly.com/external-resources#serving-dash's-component-libraries-locally-or-from-a-cdn), which reduces load on the server and can improve performance. Vizro uses [jsDeliver](https://www.jsdelivr.com/) as a CDN for CSS and JavaScript sources.
- `assets_external_path`: when `serve_locally=False`, you can also set `assets_external_path` or an environment variable `DASH_ASSETS_EXTERNAL_PATH` to [serve your own assets from a CDN](https://dash.plotly.com/external-resources#load-assets-from-a-folder-hosted-on-a-cdn).
diff --git a/vizro-core/docs/pages/user-guides/selectors.md b/vizro-core/docs/pages/user-guides/selectors.md
index 10481d2ba..a1bd4be20 100644
--- a/vizro-core/docs/pages/user-guides/selectors.md
+++ b/vizro-core/docs/pages/user-guides/selectors.md
@@ -6,10 +6,7 @@ The [`Filter`][vizro.models.Filter] or the [`Parameter`][vizro.models.Parameter]
## Categorical selectors
-Within the categorical selectors, a clear distinction exists between multi-option and single-option selectors.
-For instance, the [`Checklist`][vizro.models.Checklist] functions as a multi-option selector by default while
-the [`RadioItem`][vizro.models.RadioItems] serves as a single-option selector by default. However, the
-[`Dropdown`][vizro.models.Dropdown] can function as both a multi-option or single-option selector.
+Within the categorical selectors, a clear distinction exists between multi-option and single-option selectors. For instance, the [`Checklist`][vizro.models.Checklist] functions as a multi-option selector by default while the [`RadioItem`][vizro.models.RadioItems] serves as a single-option selector by default. However, the [`Dropdown`][vizro.models.Dropdown] can function as both a multi-option or single-option selector.
For more information, refer to the API reference of the selector, or the documentation of its underlying Dash component:
@@ -18,15 +15,12 @@ For more information, refer to the API reference of the selector, or the documen
- [`RadioItems`][vizro.models.RadioItems] based on [`dcc.RadioItems`](https://dash.plotly.com/dash-core-components/radioitems)
!!! note
-
- When configuring the `options` of the categorical selectors, you can either provide:
+ When configuring the `options` of the categorical selectors, you can either give:
- a list of values `options = ['Value A', 'Value B', 'Value C']`
- or a dictionary of label-value mappings `options=[{'label': 'True', 'value': True}, {'label': 'False', 'value': False}]`
- The later is required if you want to provide different display labels to your option values or in case you want to
- provide boolean values as options. In this case, you need to provide a string label for your boolean values as
- boolean values cannot be displayed properly as labels in the underlying Dash components.
+ The later is required if you want to provide different display labels to your option values or in case you want to provide boolean values as options. In this case, you need to provide a string label for your boolean values as boolean values cannot be displayed properly as labels in the underlying Dash components.
## Numerical selectors
@@ -36,11 +30,7 @@ For more information, refer to the API reference of the selector, or the documen
- [`RangeSlider`][vizro.models.RangeSlider] based on [`dcc.RangeSlider`](https://dash.plotly.com/dash-core-components/rangeslider)
!!! note
-
- When configuring the [`Slider`][vizro.models.Slider] and the [`RangeSlider`][vizro.models.RangeSlider] with float values, and using `step` with an integer value, you may notice
- unexpected behavior, such as the drag value being outside its indicated marks.
- To our knowledge, this is a current bug in the underlying [`dcc.Slider`](https://dash.plotly.com/dash-core-components/slider) and
- [`dcc.RangeSlider`](https://dash.plotly.com/dash-core-components/rangeslider) component, which you can circumvent by adapting the `step` size accordingly.
+ When configuring the [`Slider`][vizro.models.Slider] and the [`RangeSlider`][vizro.models.RangeSlider] with float values, and using `step` with an integer value, you may notice unexpected behavior, such as the drag value being outside its indicated marks. To our knowledge, this is a current bug in the underlying [`dcc.Slider`](https://dash.plotly.com/dash-core-components/slider) and [`dcc.RangeSlider`](https://dash.plotly.com/dash-core-components/rangeslider) component, which you can circumvent by adapting the `step` size as needed.
## Temporal selectors
@@ -49,7 +39,6 @@ For more information, refer to the API reference of the selector, or the documen
- [`DatePicker`][vizro.models.DatePicker] based on [`dmc.DateRangePicker`](https://www.dash-mantine-components.com/components/datepicker#daterangepicker) and [`dmc.DatePicker`](https://www.dash-mantine-components.com/components/datepicker)
!!! note
-
When the [`DatePicker`][vizro.models.DatePicker] is configured with `range=True` (the default), the underlying component is `dmc.DateRangePicker`. When `range=False` the underlying component is `dmc.DatePicker`.
When configuring the [`DatePicker`][vizro.models.DatePicker] make sure to provide your dates for `min`, `max` and `value` arguments in `"yyyy-mm-dd"` format or as `datetime` type (for example, `datetime.datetime(2024, 01, 01)`).
diff --git a/vizro-core/docs/pages/user-guides/table.md b/vizro-core/docs/pages/user-guides/table.md
index 19197c465..80e8e53dc 100755
--- a/vizro-core/docs/pages/user-guides/table.md
+++ b/vizro-core/docs/pages/user-guides/table.md
@@ -2,46 +2,32 @@
This guide shows you how to visualize tables in Vizro.
-There are two ways to visualize tables in Vizro, using either [AG Grid](#ag-grid) or [Dash DataTable](#dash-datatable).
-In general, [AG Grid](#ag-grid) is Vizro's recommended table implementation, but sometimes it may make sense to use the [Dash DataTable](#dash-datatable) instead.
+There are two ways to visualize tables in Vizro, using either [AG Grid](#ag-grid) or [Dash DataTable](#dash-datatable). In general, [AG Grid](#ag-grid) is Vizro's recommended table implementation, but sometimes it may make sense to use the [Dash DataTable](#dash-datatable) instead.
## Choose between AG Grid and Dash DataTable
-Vizro offers two models - the [`AgGrid`][vizro.models.AgGrid] model and the [`Table`][vizro.models.Table] model - for the above two approaches respectively.
-They both visualize tabular data in similar ways.
+Vizro offers two models - the [`AgGrid`][vizro.models.AgGrid] model and the [`Table`][vizro.models.Table] model - for the above two approaches respectively. They both visualize tabular data in similar ways.
-The main difference between the two is that the [`AgGrid`][vizro.models.AgGrid] model is based on Plotly's [Dash AG Grid](https://dash.plotly.com/dash-ag-grid) component,
-while the [`Table`][vizro.models.Table] model is based on the [Dash DataTable](https://dash.plotly.com/datatable) component.
-
-Both approaches have similar base features, and are configurable in similar ways. However, the AG Grid offers more advanced features out-of-the-box, is more customizable
-and also ships a powerful enterprise version. This is why it is Vizro's recommended table implementation. At the same time, the Dash DataTable can be used if developers are
-already familiar with it, or if some custom functionality is easier to implement using the Dash DataTable.
+The main difference between the two is that the [`AgGrid`][vizro.models.AgGrid] model is based on Plotly's [Dash AG Grid](https://dash.plotly.com/dash-ag-grid) component, while the [`Table`][vizro.models.Table] model is based on the [Dash DataTable](https://dash.plotly.com/datatable) component.
+Both approaches have similar base features, and are configurable in similar ways. However, the AG Grid offers more advanced features out-of-the-box, is more customizable and also ships a powerful enterprise version. This is why it is Vizro's recommended table implementation. At the same time, the Dash DataTable can be used if developers are already familiar with it, or if some custom functionality is easier to implement using the Dash DataTable.
## AG Grid
-[AG Grid](https://www.ag-grid.com/) is an interactive table/grid component designed for viewing, editing, and exploring large datasets. It
-is Vizro's recommended table implementation.
+[AG Grid](https://www.ag-grid.com/) is an interactive table/grid component designed for viewing, editing, and exploring large datasets. It is Vizro's recommended table implementation.
-The Vizro [`AgGrid`][vizro.models.AgGrid] model is based on the [Dash AG Grid](https://dash.plotly.com/dash-ag-grid), which is in turn based the
-original [Javascript implementation](https://www.ag-grid.com/).
+The Vizro [`AgGrid`][vizro.models.AgGrid] model is based on the [Dash AG Grid](https://dash.plotly.com/dash-ag-grid), which is in turn based the original [Javascript implementation](https://www.ag-grid.com/).
### Basic usage
To add a [`AgGrid`][vizro.models.AgGrid] to your page, do the following:
-1. Insert the [`AgGrid`][vizro.models.AgGrid] model into the `components` argument of the
-[`Page`][vizro.models.Page] model.
-2. Enter the `dash_ag_grid` function under the `figure` argument (imported via `from vizro.tables import dash_ag_grid`).
-
-The Vizro version of this AG Grid differs in one way from the original Dash AG Grid: it requires the user to pass a pandas DataFrame as the source of data.
-As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`. Most other [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments.
-Note that some defaults are set for some arguments (for example, for `columnDefs`) to help with styling and usability.
-Sometimes a parameter may not work because it requires a callback to function. In that case you can try [creating a custom AG Grid callable](custom-tables.md).
+1. Insert the [`AgGrid`][vizro.models.AgGrid] model into the `components` argument of the [`Page`][vizro.models.Page] model.
+1. Enter the `dash_ag_grid` function under the `figure` argument (imported via `from vizro.tables import dash_ag_grid`).
+The Vizro version of this AG Grid differs in one way from the original Dash AG Grid: it requires the user to pass a pandas DataFrame as the source of data. As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`. Most other [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments. Note that some defaults are set for some arguments (for example, for `columnDefs`) to help with styling and usability. Sometimes a parameter may not work because it requires a callback to function. In that case you can try [creating a custom AG Grid callable](custom-tables.md).
!!! example "Basic Dash AG Grid"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -59,29 +45,28 @@ Sometimes a parameter may not work because it requires a callback to function. I
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - figure:
- _target_: dash_ag_grid
- data_frame: gapminder
- type: ag_grid
- title: Default Dash AG Grid
+ - components:
+ - figure:
+ _target_: dash_ag_grid
+ data_frame: gapminder
+ type: ag_grid
+ title: Default Dash AG Grid
```
- === "Result"
- [![AGGrid]][AGGrid]
- [AGGrid]: ../../assets/user_guides/table/aggrid.png
+ === "Result"
+ [![AGGrid]][aggrid]
### Enable pagination
-Pagination is a visual alternative to using vertical scroll. It can also improve loading time if you have many rows.
-You can turn it on by setting `dashGridOptions={"pagination": True}`.
-!!! example "Basic Dash AG Grid"
+Pagination is a visual alternative to using vertical scroll. It can also improve loading time if you have many rows. You can turn it on by setting `dashGridOptions={"pagination": True}`.
+!!! example "Basic Dash AG Grid"
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -99,37 +84,34 @@ You can turn it on by setting `dashGridOptions={"pagination": True}`.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - figure:
- _target_: dash_ag_grid
- data_frame: gapminder
- dashGridOptions:
- pagination: true
- type: ag_grid
- title: Dash AG Grid with pagination
+ - components:
+ - figure:
+ _target_: dash_ag_grid
+ data_frame: gapminder
+ dashGridOptions:
+ pagination: true
+ type: ag_grid
+ title: Dash AG Grid with pagination
```
- === "Result"
- [![AGGrid]][AGGrid]
- [AGGrid]: ../../assets/user_guides/table/aggrid-pagination.png
+ === "Result"
+ [![AGGrid]][aggrid]
### Formatting columns
#### Numbers
-One of the most common tasks when working with tables is to format the columns so that displayed numbers are more readable.
-To do this, you can use the native functionality of [value formatters](https://dash.plotly.com/dash-ag-grid/value-formatters)
-or the Vizro pre-defined [custom cell data types](https://dash.plotly.com/dash-ag-grid/cell-data-types#providing-custom-cell-data-types) as shown below.
+One of the most common tasks when working with tables is to format the columns so that displayed numbers are more readable. To do this, you can use the native functionality of [value formatters](https://dash.plotly.com/dash-ag-grid/value-formatters) or the Vizro pre-defined [custom cell data types](https://dash.plotly.com/dash-ag-grid/cell-data-types#providing-custom-cell-data-types) as shown below.
The available custom cell types for Vizro are `dollar`, `euro`, `percent` and `numeric`.
-To use these, define your desired `` alongside the chosen `cellDataType` in
-the `columnDefs` argument of your `dash_ag_grid` function:
+To use these, define your desired `` alongside the chosen `cellDataType` in the `columnDefs` argument of your `dash_ag_grid` function:
```py
columnDefs = [{"field": "", "cellDataType": "euro"}]
@@ -138,7 +120,6 @@ columnDefs = [{"field": "", "cellDataType": "euro"}]
In the example below we select and format some columns of the gapminder data.
!!! example "AG Grid with formatted columns"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -168,6 +149,7 @@ In the example below we select and format some columns of the gapminder data.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -190,33 +172,23 @@ In the example below we select and format some columns of the gapminder data.
type: ag_grid
title: Example of AG Grid with formatted columns
```
- === "Result"
- [![AGGrid2]][AGGrid2]
- [AGGrid2]: ../../assets/user_guides/table/formatted_aggrid.png
+ === "Result"
+ [![AGGrid2]][aggrid2]
#### Dates
-For the [`AgGrid`][vizro.models.AgGrid] model to sort and filter dates correctly, the date must either be of
-string format `yyyy-mm-dd` (see [Dash AG Grid docs](https://dash.plotly.com/dash-ag-grid/date-filters#example:-date-filter))
-or a pandas datetime object. Any pandas datetime column will be transformed into the `yyyy-mm-dd` format automatically.
+For the [`AgGrid`][vizro.models.AgGrid] model to sort and filter dates correctly, the date must either be of string format `yyyy-mm-dd` (see [Dash AG Grid docs](https://dash.plotly.com/dash-ag-grid/date-filters#example:-date-filter)) or a pandas datetime object. Any pandas datetime column will be transformed into the `yyyy-mm-dd` format automatically.
#### Objects and strings
-No specific formatting is available for custom objects and strings, however you can make use of [Value Formatters](https://dash.plotly.com/dash-ag-grid/value-formatters)
-to format displayed strings automatically.
-
+No specific formatting is available for custom objects and strings, however you can make use of [Value Formatters](https://dash.plotly.com/dash-ag-grid/value-formatters) to format displayed strings automatically.
### Styling and changing the AG Grid
-As mentioned above, all [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments. Below you can find
-an example of a styled AG Grid where some conditional formatting is applied, and where the columns are editable, but
-not filterable or resizable. There are more ways to alter the grid beyond this showcase. AG Grid, like any other Vizro
-component, can be customized using custom CSS. You can find information in
-the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-selected-components).
+As mentioned above, all [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments. Below you can find an example of a styled AG Grid where some conditional formatting is applied, and where the columns are editable, but not filterable or resizable. There are more ways to alter the grid beyond this showcase. AG Grid, like any other Vizro component, can be customized using custom CSS. You can find information in the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-selected-components).
!!! example "Styled and modified Dash AG Grid"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -284,6 +256,7 @@ the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-select
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -299,28 +272,28 @@ the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-select
- field: year
- field: lifeExp
valueFormatter:
- function: "d3.format('.1f')(params.value)"
+ function: d3.format('.1f')(params.value)
- field: gdpPercap
valueFormatter:
- function: "d3.format('$,.1f')(params.value)"
+ function: d3.format('$,.1f')(params.value)
cellStyle:
styleConditions:
- condition: params.value < 1045
style:
- backgroundColor: "#ff9222"
+ backgroundColor: '#ff9222'
- condition: params.value >= 1045 && params.value <= 4095
style:
- backgroundColor: "#de9e75"
+ backgroundColor: '#de9e75'
- condition: params.value > 4095 && params.value <= 12695
style:
- backgroundColor: "#aaa9ba"
+ backgroundColor: '#aaa9ba'
- condition: params.value > 12695
style:
- backgroundColor: "#00b4ff"
+ backgroundColor: '#00b4ff'
- field: pop
type: rightAligned
valueFormatter:
- function: "d3.format(',.0f')(params.value)"
+ function: d3.format(',.0f')(params.value)
defaultColDef:
resizable: false
filter: false
@@ -329,10 +302,9 @@ the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-select
type: ag_grid
title: Example of a Dash AG Grid
```
- === "Result"
- [![AGGrid3]][AGGrid3]
- [AGGrid3]: ../../assets/user_guides/table/styled_aggrid.png
+ === "Result"
+ [![AGGrid3]][aggrid3]
If the available arguments are not sufficient, there is always the option to [create a custom AG Grid callable](custom-tables.md).
@@ -348,19 +320,14 @@ The Vizro [`Table`][vizro.models.Table] model is based on the [Dash DataTable](h
To add a [`Table`][vizro.models.Table] to your page, do the following:
-1. Insert the [`Table`][vizro.models.Table] model into the `components` argument of the
-[`Page`][vizro.models.Page] model.
-2. Enter the `dash_data_table` function under the `figure` argument (imported via `from vizro.tables import dash_data_table`).
-
+1. Insert the [`Table`][vizro.models.Table] model into the `components` argument of the [`Page`][vizro.models.Page] model.
+1. Enter the `dash_data_table` function under the `figure` argument (imported via `from vizro.tables import dash_data_table`).
-The Vizro version of this table differs in one way from the original table: it requires the user to pass a pandas DataFrame as the source of data.
-As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`.
+The Vizro version of this table differs in one way from the original table: it requires the user to pass a pandas DataFrame as the source of data. As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`.
-All other [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Note that we are
-setting some defaults for some arguments to help with styling.
+All other [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Note that we are setting some defaults for some arguments to help with styling.
!!! example "Dash DataTable"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -380,31 +347,29 @@ setting some defaults for some arguments to help with styling.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: dash_data_table
- data_frame: gapminder_2007
- title: Dash DataTable
- type: table
- title: Example of a Dash DataTable
+ - components:
+ - figure:
+ _target_: dash_data_table
+ data_frame: gapminder_2007
+ title: Dash DataTable
+ type: table
+ title: Example of a Dash DataTable
```
- === "Result"
- [![Table]][Table]
- [Table]: ../../assets/user_guides/table/table.png
+ === "Result"
+ [![Table]][table]
### Styling and changing the Dash DataTable
-As mentioned above, all [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Below you can find
-an example of a styled table where some conditional formatting is applied. There are many more ways to alter the table beyond this showcase.
+As mentioned above, all [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Below you can find an example of a styled table where some conditional formatting is applied. There are many more ways to alter the table beyond this showcase.
!!! example "Styled Dash DataTable"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -467,6 +432,7 @@ an example of a styled table where some conditional formatting is applied. There
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -504,12 +470,12 @@ an example of a styled table where some conditional formatting is applied. There
backgroundColor: dodgerblue
color: white
- if:
- filter_query: "{lifeExp} < 55"
+ filter_query: '{lifeExp} < 55'
column_id: lifeExp
- backgroundColor: "#85144b"
+ backgroundColor: '#85144b'
color: white
- if:
- filter_query: "{gdpPercap} > 10000"
+ filter_query: '{gdpPercap} > 10000'
column_id: gdpPercap
backgroundColor: green
color: white
@@ -524,26 +490,20 @@ an example of a styled table where some conditional formatting is applied. There
title: Dash DataTable
```
- === "Result"
- [![Table2]][Table2]
- [Table2]: ../../assets/user_guides/table/styled_table.png
+ === "Result"
+ [![Table2]][table2]
If the available arguments are not sufficient, there is always the option to create a [custom Dash DataTable](custom-tables.md).
-
## Add title, header, and footer
-The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] models accept a `title`, `header` and
-`footer` argument. This is useful for providing context to the data being displayed, or for adding a description of
-the data.
+The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] models accept a `title`, `header` and `footer` argument. This is useful for providing context to the data being displayed, or for adding a description of the data.
- **title**: Displayed as an [H3 header](https://dash.plotly.com/dash-html-components/h3), useful for summarizing the main topic or insight of the component.
- **header**: Accepts markdown text, ideal for extra descriptions, subtitles, or detailed data insights.
- **footer**: Accepts markdown text, commonly used for citing data sources, providing information on the last update, or adding disclaimers.
-
-
### Formatted AgGrid
!!! example "Formatted AgGrid"
@@ -571,30 +531,29 @@ the data.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: dash_ag_grid
- data_frame: gapminder_2007
- dashGridOptions:
- pagination: true
- title: Gapminder Data Insights
- header: |
- #### An Interactive Exploration of Global Health, Wealth, and Population
- footer: |
- SOURCE: **Plotly gapminder data set, 2024**
- type: ag_grid
- title: Formatted AgGrid
+ - components:
+ - figure:
+ _target_: dash_ag_grid
+ data_frame: gapminder_2007
+ dashGridOptions:
+ pagination: true
+ title: Gapminder Data Insights
+ header: |
+ #### An Interactive Exploration of Global Health, Wealth, and Population
+ footer: |
+ SOURCE: **Plotly gapminder data set, 2024**
+ type: ag_grid
+ title: Formatted AgGrid
```
- === "Result"
- [![FormattedGrid]][FormattedGrid]
-
- [FormattedGrid]: ../../assets/user_guides/components/formatted_aggrid.png
+ === "Result"
+ [![FormattedGrid]][formattedgrid]
### Formatted DataTable
@@ -623,24 +582,32 @@ the data.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: dash_data_table
- data_frame: gapminder_2007
- title: Gapminder Data Insights
- header: |
- #### An Interactive Exploration of Global Health, Wealth, and Population
- footer: |
- SOURCE: **Plotly gapminder data set, 2024**
- type: table
- title: Formatted DataTable
+ - components:
+ - figure:
+ _target_: dash_data_table
+ data_frame: gapminder_2007
+ title: Gapminder Data Insights
+ header: |
+ #### An Interactive Exploration of Global Health, Wealth, and Population
+ footer: |
+ SOURCE: **Plotly gapminder data set, 2024**
+ type: table
+ title: Formatted DataTable
```
- === "Result"
- [![FormattedTable]][FormattedTable]
- [FormattedTable]: ../../assets/user_guides/components/formatted_table.png
+ === "Result"
+ [![FormattedTable]][formattedtable]
+
+[aggrid]: ../../assets/user_guides/table/aggrid.png
+[aggrid2]: ../../assets/user_guides/table/formatted_aggrid.png
+[aggrid3]: ../../assets/user_guides/table/styled_aggrid.png
+[formattedgrid]: ../../assets/user_guides/components/formatted_aggrid.png
+[formattedtable]: ../../assets/user_guides/components/formatted_table.png
+[table]: ../../assets/user_guides/table/table.png
+[table2]: ../../assets/user_guides/table/styled_table.png
diff --git a/vizro-core/docs/pages/user-guides/tabs.md b/vizro-core/docs/pages/user-guides/tabs.md
index 09154177e..1811d0cac 100755
--- a/vizro-core/docs/pages/user-guides/tabs.md
+++ b/vizro-core/docs/pages/user-guides/tabs.md
@@ -1,8 +1,6 @@
# How to use tabs
-[`Tabs`][vizro.models.Tabs] organize and separate groups of related content in a dashboard, letting users switch between different sections or views.
-They are essentially a way of putting multiple [`Containers`][vizro.models.Container] in the same screen space, and letting the user switch between them.
-`Containers` enable the grouping of page components into sections and subsections. See our [user guide on `Containers`](container.md) for more information.
+[`Tabs`][vizro.models.Tabs] organize and separate groups of related content in a dashboard, letting users switch between different sections or views. They are essentially a way of putting multiple [`Containers`][vizro.models.Container] in the same screen space, and letting the user switch between them. `Containers` enable the grouping of page components into sections and subsections. See our [user guide on `Containers`](container.md) for more information.
{ width="400"}
@@ -16,14 +14,12 @@ This guide shows you how to use tabs to organize your `Containers` into subsecti
By using [`Tabs`][vizro.models.Tabs], the following applies:
- [`Filters`][vizro.models.Filter] affect all components on all tabs (opened and closed) of the page if not specified otherwise inside `Filter.targets`
-- The `title` of the [`Container`][vizro.models.Container] inserted into `Tabs.tabs` will be displayed as a tab label, and the title will be removed from the `Container`
-
+- The `title` of the [`Container`][vizro.models.Container] inserted into `Tabs.tabs` will be displayed as a tab label, and the title will be removed from the `Container`
To add [`Tabs`][vizro.models.Tabs] to your page, do the following:
1. Insert the [`Tabs`][vizro.models.Tabs] into the `components` argument of the [`Page`][vizro.models.Page]
-2. Insert your [`Containers`][vizro.models.Container] into the `tabs` argument of the [`Tabs`][vizro.models.Tabs]
-
+1. Insert your [`Containers`][vizro.models.Container] into the `tabs` argument of the [`Tabs`][vizro.models.Tabs]
!!! example "Tabs"
=== "app.py"
@@ -88,52 +84,53 @@ To add [`Tabs`][vizro.models.Tabs] to your page, do the following:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - tabs:
- - title: Tab I
- type: container
- components:
- - type: graph
- figure:
- _target_: bar
- data_frame: gapminder_2007
- title: Graph 1
- x: continent
- y: lifeExp
- color: continent
- - type: graph
- figure:
- _target_: box
- data_frame: gapminder_2007
- title: Graph 2
- x: continent
- y: lifeExp
- color: continent
- - title: Tab II
- type: container
- components:
- - type: graph
- figure:
- _target_: scatter
- data_frame: gapminder_2007
- title: Graph 3
- x: gdpPercap
- y: lifeExp
- size: pop
- color: continent
- type: tabs
+ components:
+ - type: tabs
+ tabs:
+ - title: Tab I
+ type: container
+ components:
+ - type: graph
+ figure:
+ _target_: bar
+ data_frame: gapminder_2007
+ title: Graph 1
+ x: continent
+ y: lifeExp
+ color: continent
+ - type: graph
+ figure:
+ _target_: box
+ data_frame: gapminder_2007
+ title: Graph 2
+ x: continent
+ y: lifeExp
+ color: continent
+ - title: Tab II
+ type: container
+ components:
+ - type: graph
+ figure:
+ _target_: scatter
+ data_frame: gapminder_2007
+ title: Graph 3
+ x: gdpPercap
+ y: lifeExp
+ size: pop
+ color: continent
controls:
- - type: filter
- column: continent
+ - type: filter
+ column: continent
title: Tabs
```
- === "Result"
- [![Tabs]][Tabs]
+ === "Result"
+ [![Tabs]][tabs]
- [Tabs]: ../../assets/user_guides/components/tabs.png
+[tabs]: ../../assets/user_guides/components/tabs.png
diff --git a/vizro-core/docs/pages/user-guides/themes.md b/vizro-core/docs/pages/user-guides/themes.md
index 6f78441d5..ac1d6fc7b 100644
--- a/vizro-core/docs/pages/user-guides/themes.md
+++ b/vizro-core/docs/pages/user-guides/themes.md
@@ -1,15 +1,13 @@
# How to use themes
-This guide shows you how to use themes. Themes are pre-designed collections of stylings that are applied to entire charts and dashboards.
-The themes provided by Vizro are infused with our design best practices that make charts and dashboards look visually consistent and professional.
+This guide shows you how to use themes. Themes are pre-designed collections of stylings that are applied to entire charts and dashboards. The themes provided by Vizro are infused with our design best practices that make charts and dashboards look visually consistent and professional.
## Themes in dashboards
-The [`Dashboard`][vizro.models.Dashboard] model accepts an optional `theme` argument, where you can choose between
-a `vizro_dark` and a `vizro_light` theme. If not specified then `theme` defaults to `vizro_dark`. The theme is applied to the entire dashboard and its charts/components when a user first loads your dashboard. Regardless of the theme applied on first load, users can always switch between light and dark themes via the toggle button in the upper-right corner of the dashboard.
+
+The [`Dashboard`][vizro.models.Dashboard] model accepts an optional `theme` argument, where you can choose between a `vizro_dark` and a `vizro_light` theme. If not specified then `theme` defaults to `vizro_dark`. The theme is applied to the entire dashboard and its charts/components when a user first loads your dashboard. Regardless of the theme applied on first load, users can always switch between light and dark themes via the toggle button in the upper-right corner of the dashboard.
!!! example "Change theme"
=== "app.py"
-
```{.python pycafe-link hl_lines="18"}
import vizro.models as vm
import vizro.plotly.express as px
@@ -32,47 +30,40 @@ a `vizro_dark` and a `vizro_light` theme. If not specified then `theme` defaults
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml hl_lines="12"
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: scatter_matrix
- color: species
- data_frame: iris
- dimensions: ["sepal_length", "sepal_width", "petal_length", "petal_width"]
- type: graph
- title: Changing themes
+ - components:
+ - figure:
+ _target_: scatter_matrix
+ color: species
+ data_frame: iris
+ dimensions: [sepal_length, sepal_width, petal_length, petal_width]
+ type: graph
+ title: Changing themes
theme: vizro_light
```
+
=== "Result - vizro_light"
- [![Light]][Light]
+ [![Light]][light]
- [Light]: ../../assets/user_guides/themes/light.png
=== "Result - vizro_dark"
- [![Dark]][Dark]
-
- [Dark]: ../../assets/user_guides/themes/dark.png
-
+ [![Dark]][dark]
## Themes in plotly charts
You can also use our templates for plotly charts outside the dashboard. This is useful in a few contexts:
-* Creation of standalone charts to be used independently of a Vizro dashboard.
-* Rapid development of charts for eventual use in a Vizro dashboard, for example in a Jupyter Notebook.
+- Creation of standalone charts to be used independently of a Vizro dashboard.
+- Rapid development of charts for eventual use in a Vizro dashboard, for example in a Jupyter Notebook.
!!! note
+ Using `import vizro.plotly.express as px` is equal to using `import plotly.express as px`, but with the added benefit of being able to integrate the resulting chart code into a Vizro dashboard. Vizro offers a minimal layer on top of Plotly's existing charting library, allowing you to seamlessly use all the existing charts and functionalities provided by plotly.express without any modifications.
- Using `import vizro.plotly.express as px` is equivalent to using `import plotly.express as px`,
- but with the added benefit of being able to integrate the resulting chart code into a Vizro dashboard.
- Vizro offers a minimal layer on top of Plotly's existing charting library, allowing you to seamlessly use all the
- existing charts and functionalities provided by plotly.express without any modifications.
-
-Our `vizro_dark` and `vizro_light` themes are automatically registered to `plotly.io.templates` when importing Vizro.
-Consult the plotly documentation for [more details on how templates work in plotly](https://plotly.com/python/templates/#theming-and-templates).
+Our `vizro_dark` and `vizro_light` themes are automatically registered to `plotly.io.templates` when importing Vizro. Consult the plotly documentation for [more details on how templates work in plotly](https://plotly.com/python/templates/#theming-and-templates).
By default, plots imported from `vizro.plotly.express` have the `vizro_dark` theme applied. This can be altered either globally or for individual plots.
@@ -87,14 +78,20 @@ pio.templates.default = "vizro_light"
```
### Set themes for selected charts
+
To change the template for a selected chart only, use the `template` parameter and run:
```python
import vizro.plotly.express as px
df = px.data.iris()
-px.scatter_matrix(df,
- dimensions=["sepal_length", "sepal_width", "petal_length", "petal_width"],
- color="species",
- template="vizro_light")
+px.scatter_matrix(
+ df,
+ dimensions=["sepal_length", "sepal_width", "petal_length", "petal_width"],
+ color="species",
+ template="vizro_light",
+)
```
+
+[dark]: ../../assets/user_guides/themes/dark.png
+[light]: ../../assets/user_guides/themes/light.png
diff --git a/vizro-core/docs/pages/user-guides/visual-formatting.md b/vizro-core/docs/pages/user-guides/visual-formatting.md
index 7b384f3e9..56d1d2d52 100644
--- a/vizro-core/docs/pages/user-guides/visual-formatting.md
+++ b/vizro-core/docs/pages/user-guides/visual-formatting.md
@@ -1,17 +1,13 @@
# How to customize the style of Vizro dashboards
-Vizro has a default styling to help users with no design experience get started.
-There are several options if you want to customize the style:
+Vizro has a default styling to help users with no design experience get started. There are several options if you want to customize the style:
-* **[Configure the `Layout`](layouts.md)**: Customize the arrangement of your components inside your Vizro dashboard.
+- **[Configure the `Layout`](layouts.md)**: Customize the arrangement of your components inside your Vizro dashboard.
-* **[Apply a theme](themes.md)**: Choose between a dark or light theme.
+- **[Apply a theme](themes.md)**: Choose between a dark or light theme.
-* **[Manage assets](assets.md)**: Enhance your dashboard by adding images, scripts, and stylesheets to your assets folder.
+- **[Manage assets](assets.md)**: Enhance your dashboard by adding images, scripts, and stylesheets to your assets folder.
-* **[Customize CSS](custom-css.md)**: Incorporate custom CSS to deviate from the default styling and create a
-unique appearance for your Vizro dashboard.
+- **[Customize CSS](custom-css.md)**: Incorporate custom CSS to deviate from the default styling and create a unique appearance for your Vizro dashboard.
-* **[Customize your `component`](components.md)**: Change the appearance of components like the [Graph](graph.md), the
-[Table](table.md) and the [AgGrid](table.md), by passing extra arguments. Refer to the relevant user guide for
-more details.
+- **[Customize your `component`](components.md)**: Change the appearance of components like the [Graph](graph.md), the [Table](table.md) and the [AgGrid](table.md), by passing extra arguments. Refer to the relevant user guide for more details.
diff --git a/vizro-core/examples/README.md b/vizro-core/examples/README.md
index 72146bfb7..53cf932b7 100644
--- a/vizro-core/examples/README.md
+++ b/vizro-core/examples/README.md
@@ -4,8 +4,7 @@ Please note that this folder contains only example dashboards that are still **i
### Vizro examples gallery
-To view a comprehensive list of available demos, please visit our [examples gallery](http://vizro.mckinsey.com/).
-There, you can explore a wide range of dashboards and applications created with Vizro.
+To view a comprehensive list of available demos, please visit our [examples gallery](http://vizro.mckinsey.com/). There, you can explore a wide range of dashboards and applications created with Vizro.
diff --git a/vizro-core/examples/visual-vocabulary/README.md b/vizro-core/examples/visual-vocabulary/README.md
index 3b298520e..e59b3103c 100644
--- a/vizro-core/examples/visual-vocabulary/README.md
+++ b/vizro-core/examples/visual-vocabulary/README.md
@@ -2,14 +2,11 @@
### Welcome to our visual vocabulary dashboard! 🎨
-This dashboard serves as a comprehensive guide for selecting and creating various types of charts. It helps you decide
-when to use each chart type, and offers sample Python code using [Plotly](https://plotly.com/python/), and
-instructions for embedding these charts into a [Vizro](https://github.com/mckinsey/vizro) dashboard.
+This dashboard serves as a comprehensive guide for selecting and creating various types of charts. It helps you decide when to use each chart type, and offers sample Python code using [Plotly](https://plotly.com/python/), and instructions for embedding these charts into a [Vizro](https://github.com/mckinsey/vizro) dashboard.
The charts in this dashboard are designed to make it easy for anyone to create beautiful and sophisticated visuals.
-Our goal is to help you understand best practices in data visualization, ensure your charts effectively communicate
-your message, and streamline the creation of high-quality, interactive visualizations.
+Our goal is to help you understand best practices in data visualization, ensure your charts effectively communicate your message, and streamline the creation of high-quality, interactive visualizations.
Created by:
@@ -19,12 +16,9 @@ Created by:
Inspired by:
-- [The FT Visual Vocabulary](https://github.com/Financial-Times/chart-doctor/blob/main/visual-vocabulary/README.md):
- [Alan Smith](https://github.com/alansmithy), [Chris Campbell](https://github.com/digitalcampbell), Ian Bott,
- Liz Faunce, Graham Parrish, Billy Ehrenberg, Paul McCallum, [Martin Stabe](https://github.com/martinstabe).
+- [The FT Visual Vocabulary](https://github.com/Financial-Times/chart-doctor/blob/main/visual-vocabulary/README.md): [Alan Smith](https://github.com/alansmithy), [Chris Campbell](https://github.com/digitalcampbell), Ian Bott, Liz Faunce, Graham Parrish, Billy Ehrenberg, Paul McCallum, [Martin Stabe](https://github.com/martinstabe).
-- [The Graphic Continuum](https://www.informationisbeautifulawards.com/showcase/611-the-graphic-continuum):
- Jon Swabish and Severino Ribecca
+- [The Graphic Continuum](https://www.informationisbeautifulawards.com/showcase/611-the-graphic-continuum): Jon Swabish and Severino Ribecca
Credits and sources:
@@ -102,13 +96,12 @@ The dashboard is still in development. Below is an overview of the chart types f
Contributions are welcome! To contribute a chart, follow the steps below:
1. Check that a `svg` file named after the chart type is contained in the [assets](https://github.com/mckinsey/vizro/tree/main/vizro-core/examples/visual-vocabulary/assets/images/charts) folder. If not, [raise an issue](https://github.com/mckinsey/vizro/issues) in the repository.
-2. Add a `.py` file containing a code example of the chart type in the `pages/examples` folder, for instance, `area.py`. Take a look at existing examples.
-3. Create a new page for the chart type and add it to the relevant category `.py` file such as `correlation.py`,
- `deviation.py`, `distribution.py`, etc. Ensure you add the page to the list of `pages` at the end of the `.py` file.
-4. Remove the `IncompletePage(..)` entry for that chart type in `chart_groups.py`.
-5. Update this `README.md` with the new chart type, its status, category, and API links.
+1. Add a `.py` file containing a code example of the chart type in the `pages/examples` folder, for instance, `area.py`. Take a look at existing examples.
+1. Create a new page for the chart type and add it to the relevant category `.py` file such as `correlation.py`, `deviation.py`, `distribution.py`, etc. Ensure you add the page to the list of `pages` at the end of the `.py` file.
+1. Remove the `IncompletePage(..)` entry for that chart type in `chart_groups.py`.
+1. Update this `README.md` with the new chart type, its status, category, and API links.
## How to run the example locally
1. Run the example with the command `hatch run example visual-vocabulary`.
-2. You should now be able to access the app locally via http://127.0.0.1:8051/.
+1. You should now be able to access the app locally via http://127.0.0.1:8051/.
-
```
-
-* **Main element with `id`:** There is a `
-
+ Lorem ipsum dolor sit amet consectetur adipisicing elit.
-
+
+ Lorem ipsum dolor sit amet consectetur adipisicing elit. +
+` with our `id="custom-card"`.
-* **Parent element:** That `
` is wrapped inside a parent `
` with the class name `"card"`. This is the element we need to target to change the background color.
-* **Child element:** The card text is wrapped inside a `
` that is a child of the `
` with our `id`. This is the element we need to target to change the font color.
+
+- **Main element with `id`:** There is a `
` with our `id="custom-card"`.
+- **Parent element:** That `
` is wrapped inside a parent `
` with the class name `"card"`. This is the element we need to target to change the background color.
+- **Child element:** The card text is wrapped inside a `
` that is a child of the `
` with our `id`. This is the element we need to target to change the font color.
!!! example "Customizing CSS properties in selective components"
=== "my_css_file.css"
- ```css
- /* Apply styling to parent */
- .card:has(#custom-card) {
- background-color: white;
- }
+ ```css
+ /* Apply styling to parent */
+ .card:has(#custom-card) {
+ background-color: white;
+ }
+
+ /* Apply styling to child */
+ #custom-card p {
+ color: black;
+ }
+ ```
- /* Apply styling to child */
- #custom-card p {
- color: black;
- }
- ```
=== "app.py"
```py
import vizro.models as vm
@@ -285,77 +272,65 @@ It's essential to understand the relationship between the targeted CSS class or
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- Lorem ipsum dolor sit amet consectetur adipisicing elit.
- type: card
- id: custom-card
- - text: |
- Lorem ipsum dolor sit amet consectetur adipisicing elit.
- type: card
- title: Changing the card color
+ - components:
+ - text: |
+ Lorem ipsum dolor sit amet consectetur adipisicing elit.
+ type: card
+ id: custom-card
+ - text: |
+ Lorem ipsum dolor sit amet consectetur adipisicing elit.
+ type: card
+ title: Changing the card color
```
- === "Result"
- [![CardCSS]][CardCSS]
-
- [CardCSS]: ../../assets/user_guides/assets/css_change_card.png
+ === "Result"
+ [![CardCSS]][cardcss]
!!! note "Relationship between model ID and CSS ID"
+ Some Vizro components produce a single HTML element with an ID that matches the model ID, allowing you to target it directly using the CSS #id selector. Other components generate multiple HTML elements. Within these, the "core" element will have an ID matching the model ID, while non-core elements may have IDs that are variations of it, such as `{model-id}-title`.
- Some Vizro components produce a single HTML element with an ID that matches the model ID, allowing you to target it
- directly using the CSS #id selector. Other components generate multiple HTML elements. Within these, the "core"
- element will have an ID matching the model ID, while non-core elements may have IDs that are variations of it,
- such as `{model-id}-title`.
-
- In all instances, you can determine the correct selector by using Chrome DevTools or a similar tool after setting the
- appropriate model ID.
-
+ In all instances, you can determine the correct selector by using Chrome DevTools or a similar tool after setting the appropriate model ID.
## Common examples
### Make your CSS responsive to theme switches with variables
-To ensure your CSS adapts to theme changes, we recommend using CSS variables (`var`) whenever possible. For a
-comprehensive list of available variable names, refer to the
-[Bootstrap documentation](https://getbootstrap.com/docs/5.3/customize/css-variables/). Note that our
-Bootstrap stylesheet is still under development, so not all Bootstrap variables are currently available.
-Additionally, you can define your own CSS variables, as demonstrated in the example on
-[changing the container background color](#change-the-styling-of-a-container).
+
+To ensure your CSS adapts to theme changes, we recommend using CSS variables (`var`) whenever possible. For a comprehensive list of available variable names, refer to the [Bootstrap documentation](https://getbootstrap.com/docs/5.3/customize/css-variables/). Note that our Bootstrap stylesheet is still under development, so not all Bootstrap variables are currently available. Additionally, you can define your own CSS variables, as demonstrated in the example on [changing the container background color](#change-the-styling-of-a-container).
### Turn off page title
+
See the example above on [hiding the page title on selected pages](#overwrite-css-for-selected-pages).
### Change the background color of a card
+
See the example above on [customizing CSS properties in selective components](#overwrite-css-for-selected-components).
### Change the global font
+
The default fonts for a Vizro app are `Inter, sans-serif, Arial, serif`.
If you need to change the global font, perhaps to adhere to branding guidelines, follow these steps:
1. Download the desired font from a font provider such as [Google Fonts](https://fonts.google.com/).
-2. Place the font file (`.ttf`, `woff2`, etc.) into your `assets` folder. Here’s an example of what the assets folder might look like:
- 
+1. Place the font file (`.ttf`, `woff2`, etc.) into your `assets` folder. Here’s an example of what the assets folder might look like:
-3. Add the font to your CSS file using the `@font-face` rule and apply the font globally to your Vizro app, making sure
-to specify fallback fonts. Add the following to your `custom.css` file:
+ 
+1. Add the font to your CSS file using the `@font-face` rule and apply the font globally to your Vizro app, making sure to specify fallback fonts. Add the following to your `custom.css` file:
```css
@font-face {
- font-family: PlayfairDisplay;
- src: url("PlayfairDisplay-VariableFont_wght.ttf") format("truetype");
+ font-family: PlayfairDisplay;
+ src: url("PlayfairDisplay-VariableFont_wght.ttf") format("truetype");
}
* {
- font-family: PlayfairDisplay, Inter, sans-serif, Arial, serif;
+ font-family: PlayfairDisplay, Inter, sans-serif, Arial, serif;
}
```
-
-4. Note that the modification above applies solely to the dashboard font. To also change the font within the
-Plotly charts, you must specify this at the beginning of your `app.py` file:
+1. Note that the modification above applies solely to the dashboard font. To also change the font within the Plotly charts, you must specify this at the beginning of your `app.py` file:
```python
import plotly.io as pio
@@ -365,44 +340,42 @@ Plotly charts, you must specify this at the beginning of your `app.py` file:
```
### Reposition the logo
-By default, the logo appears in the top left corner of the dashboard. You can move it further to the left or right by
-adjusting the `padding` of the `#page-header` element. Here is an example of how to achieve this:
+
+By default, the logo appears in the top left corner of the dashboard. You can move it further to the left or right by adjusting the `padding` of the `#page-header` element. Here is an example of how to achieve this:
```css
#page-header {
- padding-left: 8px;
+ padding-left: 8px;
}
```
-
### Change the styling of a container
-If you want to make the subsections of your dashboard stand out more, you can do this by placing your components
-inside a [Container](container.md) and changing the container's styling, for example, background color, borders, padding, etc.
-To do this, you need to change the container's CSS class. Using the DevTool, as explained in the section on
-[identifying the correct CSS selector](#identify-the-correct-css-selector), you'll find that the CSS class for the
-`Container` is `page-component-container`. You can then use this class to set a new `background-color` and `padding`.
+If you want to make the subsections of your dashboard stand out more, you can do this by placing your components inside a [Container](container.md) and changing the container's styling, for example, background color, borders, padding, etc.
+
+To do this, you need to change the container's CSS class. Using the DevTool, as explained in the section on [identifying the correct CSS selector](#identify-the-correct-css-selector), you'll find that the CSS class for the `Container` is `page-component-container`. You can then use this class to set a new `background-color` and `padding`.
!!! example "Style a container"
=== "custom.css"
- ```css
- /* Assign a variable to the dark and light theme */
- [data-bs-theme="dark"] {
- --container-bg-color: #232632;
- }
-
- [data-bs-theme="light"] {
- --container-bg-color: #F5F6F6;
- }
+ ```css
+ /* Assign a variable to the dark and light theme */
+ [data-bs-theme="dark"] {
+ --container-bg-color: #232632;
+ }
+
+ [data-bs-theme="light"] {
+ --container-bg-color: #F5F6F6;
+ }
+
+ /* Use the custom variable var(--container-bg-color) */
+ .page-component-container {
+ background: var(--container-bg-color);
+ padding: 12px;
+ }
+ ```
- /* Use the custom variable var(--container-bg-color) */
- .page-component-container {
- background: var(--container-bg-color);
- padding: 12px;
- }
- ```
=== "app.py"
```py
import vizro.models as vm
@@ -437,12 +410,12 @@ To do this, you need to change the container's CSS class. Using the DevTool, as
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - title: "Page with subsections"
+ - title: Page with subsections
layout:
grid: [[0, 1]]
components:
- type: container
- title: "Container I"
+ title: Container I
components:
- type: graph
figure:
@@ -452,7 +425,7 @@ To do this, you need to change the container's CSS class. Using the DevTool, as
y: sepal_length
color: species
- type: container
- title: "Container II"
+ title: Container II
components:
- type: graph
figure:
@@ -462,13 +435,11 @@ To do this, you need to change the container's CSS class. Using the DevTool, as
y: sepal_length
color: species
```
- === "Result"
- [![StyleContainer]][StyleContainer]
- [StyleContainer]: ../../assets/user_guides/custom_css/style-container.png
+ === "Result"
+ [![StyleContainer]][stylecontainer]
-You will notice that the background colors of the charts are different. To align it with the colors of the container,
-you can make the charts' background transparent.
+You will notice that the background colors of the charts are different. To align it with the colors of the container, you can make the charts' background transparent.
To make the background of all charts transparent:
@@ -492,3 +463,8 @@ def custom_chart(data_frame):
```
+
+[assetscss]: ../../assets/user_guides/assets/css_change.png
+[cardcss]: ../../assets/user_guides/assets/css_change_card.png
+[pagetitle]: ../../assets/user_guides/assets/css_page_title.png
+[stylecontainer]: ../../assets/user_guides/custom_css/style-container.png
diff --git a/vizro-core/docs/pages/user-guides/custom-figures.md b/vizro-core/docs/pages/user-guides/custom-figures.md
index f135127be..3a178932f 100644
--- a/vizro-core/docs/pages/user-guides/custom-figures.md
+++ b/vizro-core/docs/pages/user-guides/custom-figures.md
@@ -1,41 +1,36 @@
# How to create custom figures
-This guide explains how to create custom figures, which is useful when you need a component that reacts to
-[filter](filters.md) and [parameter](parameters.md) controls.
+This guide explains how to create custom figures, which is 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).
## When to use a custom figure
-As described in the flowchart detailing [when to use `Figure`](figure.md), custom figures should be used if
-**both** of the following conditions are met:
+
+As described in the flowchart detailing [when to use `Figure`](figure.md), custom figures should be used if **both** of the following conditions are met:
- You need a figure that doesn't fit into the existing pre-defined components ([`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid]).
- You need a figure that isn't available in our pre-defined figure functions [`vizro.figures`](../API-reference/figure-callables.md).
## Steps to create a custom figure
-1. Define a function that returns a [Dash component](https://dash.plotly.com/#open-source-component-libraries).
-This can, but does not need to, be based on code in our pre-defined figure functions in [`vizro.figures`](../API-reference/figure-callables.md).
-2. Decorate it with `@capture("figure")`.
-3. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
-4. The figure should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments
-will not react to dashboard controls such as [`Filter`](filters.md).
-5. Pass your function to the `figure` argument of the [`Figure`][vizro.models.Figure] model.
+1. Define a function that returns a [Dash component](https://dash.plotly.com/#open-source-component-libraries). This can, but does not need to, be based on code in our pre-defined figure functions in [`vizro.figures`](../API-reference/figure-callables.md).
+1. Decorate it with `@capture("figure")`.
+1. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
+1. The figure should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments will not react to dashboard controls such as [`Filter`](filters.md).
+1. Pass your function to the `figure` argument of the [`Figure`][vizro.models.Figure] model.
The following examples can be used as a base to build more sophisticated figures.
## Examples of custom figures
### Custom KPI card
-To change the design or content of our existing KPI (key performance indicator) cards from
-[`vizro.figures`](../API-reference/figure-callables.md), you can do so by following the steps described above.
-For instance, to make a KPI card with the icon positioned on the right side of the title instead of the left,
-copy and paste the [source code of `kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card) and
-adjust the return statement of the function.
+To change the design or content of our existing KPI (key performance indicator) cards from [`vizro.figures`](../API-reference/figure-callables.md), you can do so by following the steps described above.
+
+For instance, to make a KPI card with the icon positioned on the right side of the title instead of the left, copy and paste the [source code of `kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card) and adjust the return statement of the function.
+
!!! example "Custom KPI card"
=== "app.py"
```{.python pycafe-link}
@@ -107,29 +102,26 @@ adjust the return statement of the function.
```
1. Here we decorate our custom figure function with the `@capture("figure")` decorator.
- 2. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
- 3. We adjust the return statement to include the icon on the right side of the title. This is achieved by swapping the order of the `html.H2` and `html.P` compared to the original `kpi_card`.
- 4. This creates a [`layout`](layouts.md) with four rows and columns. The KPI cards are positioned in the first two cells, while the remaining cells are empty.
- 5. For more information, refer to the API reference for the [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card).
- 6. Our custom figure function `custom_kpi_card` now needs to be passed on to the `vm.Figure`.
+ 1. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
+ 1. We adjust the return statement to include the icon on the right side of the title. This is achieved by swapping the order of the `html.H2` and `html.P` compared to the original `kpi_card`.
+ 1. This creates a [`layout`](layouts.md) with four rows and columns. The KPI cards are positioned in the first two cells, while the remaining cells are empty.
+ 1. For more information, refer to the API reference for the [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card).
+ 1. Our custom figure function `custom_kpi_card` now needs to be passed on to the `vm.Figure`.
=== "app.yaml"
- ```yaml
- # Custom figures are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomKPI]][CustomKPI]
+ Custom figures are currently only possible via Python configuration.
- [CustomKPI]: ../../assets/user_guides/figure/custom_kpi.png
+ === "Result"
+ [![CustomKPI]][customkpi]
### Dynamic HTML header
-You can create a custom figure for any [Dash component](https://dash.plotly.com/#open-source-component-libraries).
-Below is an example of a custom figure that returns a `html.H2` component that dynamically updates based on the selected
-name from a filter.
+
+You can create a custom figure for any [Dash component](https://dash.plotly.com/#open-source-component-libraries). Below is an example of a custom figure that returns a `html.H2` component that dynamically updates based on the selected name from a filter.
+
!!! example "Dynamic HTML header"
=== "app.py"
```{.python pycafe-link}
@@ -159,27 +151,24 @@ name from a filter.
```
1. Here we decorate our custom figure function with the `@capture("figure")` decorator.
- 2. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
- 3. We return a `html.H2` component that dynamically updates based on the selected name from the filter.
- 4. Our custom figure function `dynamic_html_header` now needs to be passed on to the `vm.Figure`.
+ 1. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
+ 1. We return a `html.H2` component that dynamically updates based on the selected name from the filter.
+ 1. Our custom figure function `dynamic_html_header` now needs to be passed on to the `vm.Figure`.
=== "app.yaml"
- ```yaml
- # Custom figures are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomHTML]][CustomHTML]
+ Custom figures are currently only possible via Python configuration.
- [CustomHTML]: ../../assets/user_guides/figure/custom_html.png
+ === "Result"
+ [![CustomHTML]][customhtml]
-
### Dynamic number of cards
-The example below shows how to create multiple cards created from a `pandas.DataFrame` where the
-number of cards displayed dynamically adjusts based on a `vm.Parameter`.
+
+The example below shows how to create multiple cards created from a `pandas.DataFrame` where the number of cards displayed dynamically adjusts based on a `vm.Parameter`.
+
!!! example "Dynamic number of cards"
=== "app.py"
```py
@@ -239,40 +228,39 @@ number of cards displayed dynamically adjusts based on a `vm.Parameter`.
```
1. Here we decorate our custom figure function with the `@capture("figure")` decorator.
- 2. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
- 3. Our decorated figure function `multiple_cards` now needs to be passed on to the `vm.Figure`.
- 4. We add a [`vm.Parameter`](parameters.md) to dynamically adjust the number of cards displayed.
- The parameter targets the `n_rows` argument of the `multiple_cards` function, determining the number of rows
- taken from the data.
+ 1. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
+ 1. Our decorated figure function `multiple_cards` now needs to be passed on to the `vm.Figure`.
+ 1. We add a [`vm.Parameter`](parameters.md) to dynamically adjust the number of cards displayed. The parameter targets the `n_rows` argument of the `multiple_cards` function, determining the number of rows taken from the data.
Run and edit this code in PyCafe
=== "styling.css"
```css
.multiple-cards-container {
- display: flex;
- flex-wrap: wrap;
- gap: 12px;
+ display: flex;
+ flex-wrap: wrap;
+ gap: 12px;
}
.figure-container {
- height: unset;
- width: unset;
+ height: unset;
+ width: unset;
}
.figure-container .card {
- height: 210px;
- width: 240px;
+ height: 210px;
+ width: 240px;
}
```
- === "app.yaml"
- ```yaml
- # Custom figures are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomFigure]][CustomFigure]
- [CustomFigure]: ../../assets/user_guides/figure/custom_multiple_cards.png
+ === "app.yaml"
+ Custom figures are currently only possible via Python configuration.
+ === "Result"
+ [![CustomFigure]][customfigure]
+
+[customfigure]: ../../assets/user_guides/figure/custom_multiple_cards.png
+[customhtml]: ../../assets/user_guides/figure/custom_html.png
+[customkpi]: ../../assets/user_guides/figure/custom_kpi.png
diff --git a/vizro-core/docs/pages/user-guides/custom-tables.md b/vizro-core/docs/pages/user-guides/custom-tables.md
index e990cfbb0..42748820b 100644
--- a/vizro-core/docs/pages/user-guides/custom-tables.md
+++ b/vizro-core/docs/pages/user-guides/custom-tables.md
@@ -1,21 +1,18 @@
# How to create custom Dash AG Grids and Dash DataTables
-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.
+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.
-The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] model accept the `figure` argument, where you can enter
-_any_ [`dash_ag_grid`][vizro.tables.dash_ag_grid] or [`dash_data_table`][vizro.tables.dash_data_table] chart as explained in the [user guide on tables](table.md).
+The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] model accept the `figure` argument, where you can enter _any_ [`dash_ag_grid`][vizro.tables.dash_ag_grid] or [`dash_data_table`][vizro.tables.dash_data_table] chart as explained in the [user guide on tables](table.md).
One reason could be that you want to create a table/grid that requires computations that can be controlled by parameters (see the example below).
### Steps to create a custom table
1. Define a function that returns a `dash_ag_grid.AgGrid` or `dash_table.DataTable` object.
-2. Decorate it with `@capture("ag_grid")` or `@capture("table")`.
-3. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
-4. The table should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments
-will not react to dashboard controls such as [`Filter`](filters.md).
-5. Pass your function to the `figure` argument of the [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid] model.
+1. Decorate it with `@capture("ag_grid")` or `@capture("table")`.
+1. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
+1. The table should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments will not react to dashboard controls such as [`Filter`](filters.md).
+1. Pass your function to the `figure` argument of the [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid] model.
The following examples show a possible version of a custom table. In this case the argument `chosen_columns` was added, which you can control with a parameter:
@@ -70,14 +67,12 @@ The following examples show a possible version of a custom table. In this case t
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
- ```yaml
- # Custom tables are currently only possible via Python configuration
- ```
- === "Result"
- [![Table3]][Table3]
+ Custom tables are currently only possible via Python configuration.
- [Table3]: ../../assets/user_guides/table/custom_table.png
+ === "Result"
+ [![Table3]][table3]
??? example "Custom Dash AgGrid"
=== "app.py"
@@ -136,11 +131,12 @@ The following examples show a possible version of a custom table. In this case t
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
- ```yaml
- # Custom Ag Grids are currently only possible via Python configuration
- ```
+ Custom Ag Grids are currently only possible via Python configuration.
+
=== "Result"
- [![GridCustom]][GridCustom]
+ [![GridCustom]][gridcustom]
- [GridCustom]: ../../assets/user_guides/table/custom_grid.png
+[gridcustom]: ../../assets/user_guides/table/custom_grid.png
+[table3]: ../../assets/user_guides/table/custom_table.png
diff --git a/vizro-core/docs/pages/user-guides/dashboard.md b/vizro-core/docs/pages/user-guides/dashboard.md
index 0b37e03fa..244f65256 100644
--- a/vizro-core/docs/pages/user-guides/dashboard.md
+++ b/vizro-core/docs/pages/user-guides/dashboard.md
@@ -1,16 +1,15 @@
# How to create a dashboard
-This guide shows you how to configure and call a [`Dashboard`][vizro.models.Dashboard] using either
-pydantic models, Python dictionaries, YAML, or JSON.
+
+This guide shows you how to configure and call a [`Dashboard`][vizro.models.Dashboard] using either pydantic models, Python dictionaries, YAML, or JSON.
To create a dashboard:
1. Choose one of the possible configuration syntaxes
-2. Create your `pages`, see our [guide on Pages](pages.md)
-3. (optional) Choose a `theme`, see our [guide on Themes](themes.md)
-4. (optional) Customize your `navigation`, see our [guide on Navigation](navigation.md)
-5. (optional) Set a `title` for your dashboard
-6. Add your `dashboard` to the `build` call of Vizro
-
+1. Create your `pages`, see our [guide on Pages](pages.md)
+1. (optional) Choose a `theme`, see our [guide on Themes](themes.md)
+1. (optional) Customize your `navigation`, see our [guide on Navigation](navigation.md)
+1. (optional) Set a `title` for your dashboard
+1. Add your `dashboard` to the `build` call of Vizro
## Use dashboard configuration options
@@ -37,6 +36,7 @@ To create a dashboard:
Vizro().build(dashboard).run()
```
+
=== "app.py - Python dict"
```py
import vizro.plotly.express as px
@@ -77,6 +77,7 @@ To create a dashboard:
Vizro().build(dashboard).run()
```
+
=== "dashboard.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -101,50 +102,49 @@ To create a dashboard:
type: filter
title: My first dashboard
```
+
=== "dashboard.json"
```json
{
- "pages": [
+ "pages": [
+ {
+ "components": [
+ {
+ "figure": {
+ "_target_": "scatter",
+ "color": "species",
+ "data_frame": "iris",
+ "x": "sepal_length",
+ "y": "petal_width"
+ },
+ "type": "graph"
+ },
{
- "components": [
- {
- "figure": {
- "_target_": "scatter",
- "color": "species",
- "data_frame": "iris",
- "x": "sepal_length",
- "y": "petal_width"
- },
- "type": "graph"
- },
- {
- "figure": {
- "_target_": "histogram",
- "color": "species",
- "data_frame": "iris",
- "x": "sepal_width",
- },
- "type": "graph"
- }
- ],
- "controls": [
- {
- "column": "species",
- "type": "filter"
- }
- ],
- "title": "My first dashboard"
+ "figure": {
+ "_target_": "histogram",
+ "color": "species",
+ "data_frame": "iris",
+ "x": "sepal_width"
+ },
+ "type": "graph"
}
- ]
+ ],
+ "controls": [
+ {
+ "column": "species",
+ "type": "filter"
+ }
+ ],
+ "title": "My first dashboard"
+ }
+ ]
}
```
- === "Result"
- [![Dashboard]][Dashboard]
- [Dashboard]: ../../assets/user_guides/dashboard/dashboard.png
+ === "Result"
+ [![Dashboard]][dashboard]
!!! note "Extra `.py` files for `yaml` and `json` required"
-
Note that in the `yaml` and `json` example an extra `.py` is required to register the data and parse the yaml/json configuration.
=== "app.py for yaml"
@@ -164,6 +164,7 @@ To create a dashboard:
Vizro().build(dashboard).run()
```
+
=== "app.py for json"
```py
import json
@@ -187,7 +188,6 @@ After running the dashboard, you can access the dashboard via `localhost:8050`.
If supplied, the `title` of the [`Dashboard`][vizro.models.Dashboard] displays a heading at the top of every page.
-
## Add a dashboard logo
Vizro will [automatically incorporate the dashboard logo](assets.md/#add-a-logo-image) in the top-left corner of each page if an image named `logo.` is present within the assets folder.
@@ -196,11 +196,10 @@ Vizro will [automatically incorporate the dashboard logo](assets.md/#add-a-logo-
## Browser title
-The [website icon](assets.md/#change-the-favicon), Dashboard `title` (if supplied) and [Page `title`][vizro.models.Page] are displayed in the browser's
-title bar. For example, if your Dashboard `title` is "Vizro Demo" and the Page `title` is "Homepage", then the title in the browser tab will be "Vizro Demo: Homepage".
+The [website icon](assets.md/#change-the-favicon), Dashboard `title` (if supplied) and [Page `title`][vizro.models.Page] are displayed in the browser's title bar. For example, if your Dashboard `title` is "Vizro Demo" and the Page `title` is "Homepage", then the title in the browser tab will be "Vizro Demo: Homepage".
## Meta tags for social media
-Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat
-clients. The preview includes the `URL`, `title`, plus an [image](assets.md/#include-a-meta-tags-image) and
-[Page `description`][vizro.models.Page] (if supplied). To see an example, try sharing an example from the [Vizro examples gallery](https://vizro.mckinsey.com/).
+Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat clients. The preview includes the `URL`, `title`, plus an [image](assets.md/#include-a-meta-tags-image) and [Page `description`][vizro.models.Page] (if supplied). To see an example, try sharing an example from the [Vizro examples gallery](https://vizro.mckinsey.com/).
+
+[dashboard]: ../../assets/user_guides/dashboard/dashboard.png
diff --git a/vizro-core/docs/pages/user-guides/data.md b/vizro-core/docs/pages/user-guides/data.md
index 51bf84b97..d19b8aafb 100644
--- a/vizro-core/docs/pages/user-guides/data.md
+++ b/vizro-core/docs/pages/user-guides/data.md
@@ -2,11 +2,12 @@
Vizro supports two different types of data:
-* [Static data](#static-data): pandas DataFrame. This is the simplest method and best to use if you do not need the more advanced functionality of dynamic data.
-* [Dynamic data](#dynamic-data): function that returns a pandas DataFrame. This is a bit more complex to understand but has more advanced functionality such as the ability to refresh data while the dashboard is running.
+- [Static data](#static-data): pandas DataFrame. This is the simplest method and best to use if you do not need the more advanced functionality of dynamic data.
+- [Dynamic data](#dynamic-data): function that returns a pandas DataFrame. This is a bit more complex to understand but has more advanced functionality such as the ability to refresh data while the dashboard is running.
The following flowchart shows what you need to consider when choosing how to set up your data.
-``` mermaid
+
+```mermaid
graph TD
refresh["`Do you need your data to refresh while the dashboard is running?`"]
specification["`Do you need to specify your dashboard through a configuration language like YAML?`"]
@@ -27,11 +28,10 @@ graph TD
```
??? note "Static vs. dynamic data comparison"
-
This table gives a full comparison between static and dynamic data. Do not worry if you do not yet understand everything in it; it will become clearer after reading more about [static data](#static-data) and [dynamic data](#dynamic-data)!
| | Static | Dynamic |
- |---------------------------------------------------------------|------------------|------------------------------------------|
+ | ------------------------------------------------------------- | ---------------- | ---------------------------------------- |
| Required Python type | pandas DataFrame | Function that returns a pandas DataFrame |
| Can be supplied directly in `data_frame` argument of `figure` | Yes | No |
| Can be referenced by name after adding to data manager | Yes | Yes |
@@ -73,14 +73,13 @@ The below example uses the Iris data saved to a file `iris.csv` in the same dire
```
1. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
- === "Result"
- [![DataBasic]][DataBasic]
- [DataBasic]: ../../assets/user_guides/data/data_pandas_dataframe.png
+ === "Result"
+ [![DataBasic]][databasic]
The [`Graph`][vizro.models.Graph], [`AgGrid`][vizro.models.AgGrid] and [`Table`][vizro.models.Table] models all have an argument called `figure`. This accepts a function (in the above example, `px.scatter`) that takes a pandas DataFrame as its first argument. The name of this argument is always `data_frame`. When configuring the dashboard using Python, it is optional to give the name of the argument: if you like, you could write `data_frame=iris` instead of `iris`.
-!!! note
+!!! note
With static data, once the dashboard is running, the data shown in the dashboard cannot change even if the source data in `iris.csv` changes. The code `iris = pd.read_csv("iris.csv")` is only executed once when the dashboard is first started. If you would like changes to source data to flow through to the dashboard then you must use [dynamic data](#dynamic-data).
### Reference by name
@@ -107,27 +106,27 @@ If you would like to specify your dashboard configuration through YAML then you
```
1. `"iris"` is the name of a data source added to the data manager. This data is a pandas DataFrame created by reading from the CSV file `iris.csv`.
+
=== "dashboard.yaml"
```yaml
pages:
- - components:
- - figure:
+ - components:
+ figure:
_target_: box
data_frame: iris # (1)!
x: species
y: petal_width
color: species
type: graph
- title: Static data example
+ title: Static data example
```
1. Refer to the `"iris"` data source in the data manager.
- === "Result"
- [![DataBasic]][DataBasic]
- [DataBasic]: ../../assets/user_guides/data/data_pandas_dataframe.png
+ === "Result"
+ [![DataBasic]][databasic]
-It is also possible to refer to a named data source using the Python API: `px.scatter("iris", ...)` or `px.scatter(data_frame="iris", ...)` would work if the `"iris"` data source has been registered in the data manager.
+It is also possible to refer to a named data source using the Python API: `px.scatter("iris", ...)` or `px.scatter(data_frame="iris", ...)` would work if the `"iris"` data source has been registered in the data manager.
## Dynamic data
@@ -166,14 +165,12 @@ The example below shows how data is fetched dynamically every time the page is r
```
1. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
- 2. To demonstrate that dynamic data can change when the page is refreshed, select 50 points at random. This simulates what would happen if your file `iris.csv` were constantly changing.
- 3. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()`; doing so would result in static data that cannot be reloaded.
- 4. Dynamic data is referenced by the name of the data source `"iris"`.
+ 1. To demonstrate that dynamic data can change when the page is refreshed, select 50 points at random. This simulates what would happen if your file `iris.csv` were constantly changing.
+ 1. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()`; doing so would result in static data that cannot be reloaded.
+ 1. Dynamic data is referenced by the name of the data source `"iris"`.
=== "Result"
- [![DynamicData]][DynamicData]
-
- [DynamicData]: ../../assets/user_guides/data/dynamic_data.gif
+ [![DynamicData]][dynamicdata]
Since dynamic data sources must always be added to the data manager and referenced by name, they may be used in YAML configuration [exactly the same way as for static data sources](#reference-by-name).
@@ -184,10 +181,10 @@ By default, a dynamic data function executes every time the dashboard is refresh
The Vizro data manager has a server-side caching mechanism to help solve this. Vizro's cache uses [Flask-Caching](https://flask-caching.readthedocs.io/en/latest/), which supports a number of possible cache backends and [configuration options](https://flask-caching.readthedocs.io/en/latest/#configuring-flask-caching). By default, the cache is turned off.
+
In a development environment the easiest way to enable caching is to use a [simple memory cache](https://cachelib.readthedocs.io/en/stable/simple/) with the default configuration options. This is achieved by adding one line to the above example to set `data_manager.cache`:
!!! example "Simple cache with default timeout of 5 minutes"
-
```py hl_lines="13"
from flask_caching import Cache
from vizro import Vizro
@@ -225,7 +222,6 @@ data_manager.cache = Cache(config={"CACHE_TYPE": "SimpleCache", "CACHE_DEFAULT_T
```
!!! warning
-
Simple cache exists purely for single-process development purposes and is not intended to be used in production. If you deploy with multiple workers, [for example with Gunicorn](run.md/#gunicorn), then you should use a production-ready cache backend. All of Flask-Caching's [built-in backends](https://flask-caching.readthedocs.io/en/latest/#built-in-cache-backends) other than `SimpleCache` are suitable for production. In particular, you might like to use [`FileSystemCache`](https://cachelib.readthedocs.io/en/stable/file/) or [`RedisCache`](https://cachelib.readthedocs.io/en/stable/redis/):
```py title="Production-ready caches"
@@ -239,7 +235,9 @@ data_manager.cache = Cache(config={"CACHE_TYPE": "SimpleCache", "CACHE_DEFAULT_T
Since Flask-Caching relies on [`pickle`](https://docs.python.org/3/library/pickle.html), which can execute arbitrary code during unpickling, you should not cache data from untrusted sources. Doing so [could be unsafe](https://github.com/pallets-eco/flask-caching/pull/209).
Note that when a production-ready cache backend is used, the cache is persisted beyond the Vizro process and is not cleared by restarting your server. To clear the cache then you must do so manually, for example, if you use `FileSystemCache` then you would delete your `cache` directory. Persisting the cache can also be useful for development purposes when handling data that takes a long time to load: even if you do not need the data to refresh while your dashboard is running, it can speed up your development loop to use dynamic data with a cache that is persisted between repeated runs of Vizro.
+
+
#### Set timeouts
You can change the timeout of the cache independently for each dynamic data source in the data manager using the `timeout` setting (measured in seconds). A `timeout` of 0 indicates that the cache does not expire. This is effectively the same as using [static data](#static-data).
@@ -278,8 +276,8 @@ In general, a parametrized dynamic data source should always return a pandas Dat
To add a parameter to control a dynamic data source, do the following:
1. add the appropriate argument to your dynamic data function and specify a default value for the argument.
-2. give an `id` to all components that have the data source you wish to alter through a parameter.
-3. [add a parameter](parameters.md) with `targets` of the form `.data_frame.` and a suitable [selector](selectors.md).
+1. give an `id` to all components that have the data source you wish to alter through a parameter.
+1. [add a parameter](parameters.md) with `targets` of the form `.data_frame.` and a suitable [selector](selectors.md).
For example, let us extend the [dynamic data example](#dynamic-data) above into an example of how parametrized dynamic data works. The `load_iris_data` can take an argument `number_of_points` controlled from the dashboard with a [`Slider`][vizro.models.Slider].
@@ -318,21 +316,18 @@ For example, let us extend the [dynamic data example](#dynamic-data) above into
```
1. `load_iris_data` takes a single argument, `number_of_points`, with a default value of 10.
- 2. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
- 3. Sample points at random, where `number_of_points` gives the number of points selected.
- 4. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()` or `load_iris_data(number_of_points=...)`; doing so would result in static data that cannot be reloaded.
- 5. Give the `vm.Graph` component `id="graph"` so that the `vm.Parameter` can target it. Dynamic data is referenced by the name of the data source `"iris"`.
- 6. Create a `vm.Parameter` to target the `number_of_points` argument for the `data_frame` used in `graph`.
+ 1. `iris` is a pandas DataFrame created by reading from the CSV file `iris.csv`.
+ 1. Sample points at random, where `number_of_points` gives the number of points selected.
+ 1. To use `load_iris_data` as dynamic data it must be added to the data manager. You should **not** actually call the function as `load_iris_data()` or `load_iris_data(number_of_points=...)`; doing so would result in static data that cannot be reloaded.
+ 1. Give the `vm.Graph` component `id="graph"` so that the `vm.Parameter` can target it. Dynamic data is referenced by the name of the data source `"iris"`.
+ 1. Create a `vm.Parameter` to target the `number_of_points` argument for the `data_frame` used in `graph`.
=== "Result"
- [![ParametrizedDynamicData]][ParametrizedDynamicData]
-
- [ParametrizedDynamicData]: ../../assets/user_guides/data/parametrized_dynamic_data.gif
+ [![ParametrizedDynamicData]][parametrizeddynamicdata]
Parametrized data loading is compatible with [caching](#configure-cache). The cache uses [memoization](https://flask-caching.readthedocs.io/en/latest/#memoization), so that the dynamic data function's arguments are included in the cache key. This means that `load_iris_data(number_of_points=10)` is cached independently of `load_iris_data(number_of_points=20)`.
!!! warning
-
You should always [treat the content of user input as untrusted](https://community.plotly.com/t/writing-secure-dash-apps-community-thread/54619). For example, you should not expose a filepath to load without passing it through a function like [`werkzeug.utils.secure_filename`](https://werkzeug.palletsprojects.com/en/3.0.x/utils/#werkzeug.utils.secure_filename), or you might enable arbitrary access to files on your server.
You cannot pass [nested parameters](parameters.md#nested-parameters) to dynamic data. You can only target the top-level arguments of the data loading function, not the nested keys in a dictionary.
@@ -354,7 +349,6 @@ When the page is refreshed, the behavior of a dynamic filter is as follows:
For example, let us add two filters to the [dynamic data example](#dynamic-data) above:
!!! example "Dynamic filters"
-
```py hl_lines="10 20 21"
from vizro import Vizro
import pandas as pd
@@ -386,8 +380,8 @@ For example, let us add two filters to the [dynamic data example](#dynamic-data)
```
1. We sample only 5 rather than 50 points so that changes to the available values in the filtered columns are more apparent when the page is refreshed.
- 2. This filter implicitly controls the dynamic data source `"iris"`, which supplies the `data_frame` to the targeted `vm.Graph`. On page refresh, Vizro reloads this data, finds all the unique values in the `"species"` column and sets the categorical selector's `options` accordingly.
- 3. Similarly, on page refresh, Vizro finds the minimum and maximum values of the `"sepal_length"` column in the reloaded data and sets new `min` and `max` values for the numerical selector accordingly.
+ 1. This filter implicitly controls the dynamic data source `"iris"`, which supplies the `data_frame` to the targeted `vm.Graph`. On page refresh, Vizro reloads this data, finds all the unique values in the `"species"` column and sets the categorical selector's `options` accordingly.
+ 1. Similarly, on page refresh, Vizro finds the minimum and maximum values of the `"sepal_length"` column in the reloaded data and sets new `min` and `max` values for the numerical selector accordingly.
Consider a filter that depends on dynamic data, where you do **not** want the available values to change when the dynamic data changes. You should manually specify the `selector`'s `options` field (categorical selector) or `min` and `max` fields (numerical selector). In the above example, this could be achieved as follows:
@@ -409,10 +403,13 @@ controls = [
When Vizro initially builds a filter that depends on parametrized dynamic data loading, data is loaded using the default argument values. This data is used to:
-* perform initial validation
-* check which data sources contain the specified `column` (unless `targets` is explicitly specified) and
-* find the type of selector to use (unless `selector` is explicitly specified).
+- perform initial validation
+- check which data sources contain the specified `column` (unless `targets` is explicitly specified) and
+- find the type of selector to use (unless `selector` is explicitly specified).
!!! note
-
When the value of a dynamic data parameter is changed by a dashboard user, the data underlying a dynamic filter can change. Currently this change affects page components such as `vm.Graph` but does not affect the available values shown in a dynamic filter, which only update on page refresh. This functionality will be coming soon!
+
+[databasic]: ../../assets/user_guides/data/data_pandas_dataframe.png
+[dynamicdata]: ../../assets/user_guides/data/dynamic_data.gif
+[parametrizeddynamicdata]: ../../assets/user_guides/data/parametrized_dynamic_data.gif
diff --git a/vizro-core/docs/pages/user-guides/extensions.md b/vizro-core/docs/pages/user-guides/extensions.md
index 2c7efc9ac..74a740448 100644
--- a/vizro-core/docs/pages/user-guides/extensions.md
+++ b/vizro-core/docs/pages/user-guides/extensions.md
@@ -2,64 +2,49 @@
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).
+- **[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.
+- **[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.
-* **[CSS customizations](#css-customizations)**. You can add custom CSS to any Vizro dashboard, enabling users to deviate from the default styling and create a unique look and feel for their dashboard.
-
-* **[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
+- **[CSS customizations](#css-customizations)**. You can add custom CSS to any Vizro dashboard, enabling users to deviate from the default styling and create a unique look and feel for their dashboard.
+- **[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
-
+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)).
+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.
-
+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).
+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
+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:
+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
@@ -93,14 +78,12 @@ enabling an interaction between data points in a scatter plot and the content of
## CSS customizations
-Vizro is opinionated about visual formatting, and some elements, such as the layout of the navigation and controls,
-are fixed. You can customize some settings such as background colors, fonts, and other styles via CSS overrides.
+Vizro is opinionated about visual formatting, and some elements, such as the layout of the navigation and controls, are fixed. You can customize some settings such as background colors, fonts, and other styles via CSS overrides.
For more information, see our documentation on [customizing CSS](custom-css.md)
## 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
+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)
diff --git a/vizro-core/docs/pages/user-guides/figure.md b/vizro-core/docs/pages/user-guides/figure.md
index 0589fad3b..03bfa412a 100644
--- a/vizro-core/docs/pages/user-guides/figure.md
+++ b/vizro-core/docs/pages/user-guides/figure.md
@@ -1,26 +1,19 @@
# How to use figures
-This guide shows you how to add any [Dash component](https://dash.plotly.com/#open-source-component-libraries) that needs to be reactive to [filter](filters.md) and [parameter](parameters.md) controls.
-If you want to add a static Dash component to your page, use [custom components](custom-components.md) instead.
+This guide shows you how to add any [Dash component](https://dash.plotly.com/#open-source-component-libraries) that needs to be reactive to [filter](filters.md) and [parameter](parameters.md) controls. If you want to add a static Dash component to your page, use [custom components](custom-components.md) instead.
-[`Figure`][vizro.models.Figure] provides a flexible foundation for all types of reactive Dash components in Vizro.
-The [`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] and [`AgGrid`][vizro.models.AgGrid] components are
-specific implementations of `Figure`. They serve as intuitive shortcuts, embedding behaviors and interactions specific
-to their purposes.
+[`Figure`][vizro.models.Figure] provides a flexible foundation for all types of reactive Dash components in Vizro. The [`Graph`][vizro.models.Graph], [`Table`][vizro.models.Table] and [`AgGrid`][vizro.models.AgGrid] components are specific implementations of `Figure`. They serve as intuitive shortcuts, embedding behaviors and interactions specific to their purposes.
-If these more specific models already achieve what you need then they should be used in preference to
-the more generic `Figure`. Remember that it is possible to supply [custom charts](custom-charts.md) to `Graph`
-and [custom tables](custom-tables.md) to `Table`.
+If these more specific models already achieve what you need then they should be used in preference to the more generic `Figure`. Remember that it is possible to supply [custom charts](custom-charts.md) to `Graph` and [custom tables](custom-tables.md) to `Table`.
-There are already a few figure functions you can reuse, see the section on [KPI cards](#key-performance-indicator-kpi-cards)
-for more details:
+There are already a few figure functions you can reuse, see the section on [KPI cards](#key-performance-indicator-kpi-cards) for more details:
- [`kpi_card`][vizro.figures.kpi_card]
- [`kpi_card_reference`][vizro.figures.kpi_card_reference]
The following flowchart shows what you need to consider when choosing which model to use:
-``` mermaid
+```mermaid
graph TD
first["`Does your desired component exist in Vizro, e.g. Graph, Table or AgGrid?`"]
specific-component([Use the specific component])
@@ -40,14 +33,12 @@ graph TD
classDef clickable color:#4051b5;
```
-
To add a `Figure` to your page:
1. Add the `Figure` model to the components argument of the [Page][vizro.models.Page] model.
-2. Use an existing figure function from [`vizro.figures`](../API-reference/figure-callables.md) and pass it to the `figure` argument of the `Figure` model.
+1. Use an existing figure function from [`vizro.figures`](../API-reference/figure-callables.md) and pass it to the `figure` argument of the `Figure` model.
!!! example "Use existing figure functions"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -99,40 +90,25 @@ To add a `Figure` to your page:
selector:
type: radio_items
layout:
- grid:
- [
- [0, -1, -1, -1],
- [-1, -1, -1, -1],
- [-1, -1, -1, -1],
- [-1, -1, -1, -1],
- [-1, -1, -1, -1],
- ]
+ grid: [[0, -1, -1, -1], [-1, -1, -1, -1], [-1, -1, -1, -1], [-1, -1, -1, -1],
+ [-1, -1, -1, -1]]
title: KPI card
```
- === "Result"
- [![Figure]][Figure]
-
- [Figure]: ../../assets/user_guides/figure/figure.png
+ === "Result"
+ [![Figure]][figure]
### Key Performance Indicator (KPI) cards
-A KPI card is a dynamic card that can display a single value, but optionally, can also include a title, icon, and reference value.
-It is a common visual component to display key metrics in a dashboard. Vizro supports two pre-defined KPI card functions:
-- [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card): A KPI card that shows a single value found
-by performing an aggregation function (by default, `sum`) over a specified column.
-Required arguments are `data_frame` and `value_column`.
+A KPI card is a dynamic card that can display a single value, but optionally, can also include a title, icon, and reference value. It is a common visual component to display key metrics in a dashboard. Vizro supports two pre-defined KPI card functions:
-- [`kpi_card_with_reference`](../API-reference/figure-callables.md#vizro.figures.kpi_card_reference): A KPI card that shows a single value
-and a delta comparison to a reference value found by performing an aggregation function (by default, `sum`) over the specified columns.
-Required arguments are `data_frame`, `value_column` and `reference_column`.
+- [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card): A KPI card that shows a single value found by performing an aggregation function (by default, `sum`) over a specified column. Required arguments are `data_frame` and `value_column`.
-As described in the [API reference](../API-reference/figure-callables.md) and illustrated in the below example, these
-functions have several arguments to customize your KPI cards. If you require a level of customization that is not
-possible with the built-in functions then you can create a [custom figure](custom-figures.md).
+- [`kpi_card_with_reference`](../API-reference/figure-callables.md#vizro.figures.kpi_card_reference): A KPI card that shows a single value and a delta comparison to a reference value found by performing an aggregation function (by default, `sum`) over the specified columns. Required arguments are `data_frame`, `value_column` and `reference_column`.
-!!! example "KPI card variations"
+As described in the [API reference](../API-reference/figure-callables.md) and illustrated in the below example, these functions have several arguments to customize your KPI cards. If you require a level of customization that cannot be done with the built-in functions then you can create a [custom figure](custom-figures.md).
+!!! example "KPI card variations"
=== "app.py"
```{.python pycafe-link}
import pandas as pd
@@ -258,8 +234,8 @@ possible with the built-in functions then you can create a [custom figure](custo
value_column: Actual
reference_column: Reference
title: KPI reference with formatting
- value_format: "{value:.2f}€"
- reference_format: "{delta:+.2f}€ vs. last year ({reference:.2f}€)"
+ value_format: '{value:.2f}€'
+ reference_format: '{delta:+.2f}€ vs. last year ({reference:.2f}€)'
type: figure
- figure:
_target_: kpi_card_reference
@@ -276,7 +252,9 @@ possible with the built-in functions then you can create a [custom figure](custo
grid: [[0, 1, 2, 3], [4, 5, 6, 7], [-1, -1, -1, -1], [-1, -1, -1, -1]]
title: KPI cards
```
+
=== "Result"
- [![KPICards]][KPICards]
+ [![KPICards]][kpicards]
- [KPICards]: ../../assets/user_guides/figure/kpi_cards.png
+[figure]: ../../assets/user_guides/figure/figure.png
+[kpicards]: ../../assets/user_guides/figure/kpi_cards.png
diff --git a/vizro-core/docs/pages/user-guides/filters.md b/vizro-core/docs/pages/user-guides/filters.md
index bc3649178..8228ecbe7 100644
--- a/vizro-core/docs/pages/user-guides/filters.md
+++ b/vizro-core/docs/pages/user-guides/filters.md
@@ -2,8 +2,7 @@
This guide shows you how to add filters to your dashboard. One main way to interact with the charts/components on your page is by filtering the underlying data. A filter selects a subset of rows of a component's underlying DataFrame which alters the appearance of that component on the page.
-The [`Page`][vizro.models.Page] model accepts the `controls` argument, where you can enter a [`Filter`][vizro.models.Filter] model.
-This model enables the automatic creation of [selectors](selectors.md) (for example, `Dropdown` or `RangeSlider`) that operate on the charts/components on the screen.
+The [`Page`][vizro.models.Page] model accepts the `controls` argument, where you can enter a [`Filter`][vizro.models.Filter] model. This model enables the automatic creation of [selectors](selectors.md) (for example, `Dropdown` or `RangeSlider`) that operate on the charts/components on the screen.
By default, filters that control components with [dynamic data](data.md#dynamic-data) are [dynamically updated](data.md#filters) when the underlying data changes while the dashboard is running.
@@ -12,7 +11,7 @@ By default, filters that control components with [dynamic data](data.md#dynamic-
To add a filter to your page, do the following:
1. add the [`Filter`][vizro.models.Filter] model into the `controls` argument of the [`Page`][vizro.models.Page] model
-2. configure the `column` argument, which denotes the target column to be filtered
+1. configure the `column` argument, which denotes the target column to be filtered
You can also set `targets` to specify which components on the page the filter should apply to. If this is not explicitly set then `targets` defaults to all components on the page whose data source includes `column`.
@@ -39,6 +38,7 @@ You can also set `targets` to specify which components on the page the filter sh
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -57,17 +57,15 @@ You can also set `targets` to specify which components on the page the filter sh
type: filter
title: My first page
```
- === "Result"
- [![Filter]][Filter]
-
- [Filter]: ../../assets/user_guides/control/control1.png
+ === "Result"
+ [![Filter]][filter]
The selector is configured automatically based on the target column type data as follows:
- - Categorical data uses [`vm.Dropdown(multi=True)`][vizro.models.Dropdown] where `options` is the set of unique values found in `column` across all the data sources of components in `targets`.
- - [Numerical data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_numeric_dtype.html) uses [`vm.RangeSlider`][vizro.models.RangeSlider] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`.
- - [Temporal data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_datetime64_any_dtype.html) uses [`vm.DatePicker(range=True)`][vizro.models.DatePicker] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`. A column can be converted to this type with [pandas.to_datetime](https://pandas.pydata.org/docs/reference/api/pandas.to_datetime.html).
+- Categorical data uses [`vm.Dropdown(multi=True)`][vizro.models.Dropdown] where `options` is the set of unique values found in `column` across all the data sources of components in `targets`.
+- [Numerical data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_numeric_dtype.html) uses [`vm.RangeSlider`][vizro.models.RangeSlider] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`.
+- [Temporal data](https://pandas.pydata.org/docs/reference/api/pandas.api.types.is_datetime64_any_dtype.html) uses [`vm.DatePicker(range=True)`][vizro.models.DatePicker] where `min` and `max` are the overall minimum and maximum values found in `column` across all the data sources of components in `targets`. A column can be converted to this type with [pandas.to_datetime](https://pandas.pydata.org/docs/reference/api/pandas.to_datetime.html).
The following example demonstrates these default selector types.
@@ -107,6 +105,7 @@ The following example demonstrates these default selector types.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -129,15 +128,13 @@ The following example demonstrates these default selector types.
type: filter
title: My first page
```
- === "Result"
- [![Filter]][Filter]
- [Filter]: ../../assets/user_guides/selectors/default_filter_selectors.png
+ === "Result"
+ [![Filter]][filter]
## Change selector
-If you want to have a different selector for your filter, you can give the `selector` argument of the [`Filter`][vizro.models.Filter] a different selector model.
-Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropdown`][vizro.models.Dropdown], [`RadioItems`][vizro.models.RadioItems], [`RangeSlider`][vizro.models.RangeSlider], [`Slider`][vizro.models.Slider], and [`DatePicker`][vizro.models.DatePicker].
+If you want to have a different selector for your filter, you can give the `selector` argument of the [`Filter`][vizro.models.Filter] a different selector model. Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropdown`][vizro.models.Dropdown], [`RadioItems`][vizro.models.RadioItems], [`RangeSlider`][vizro.models.RangeSlider], [`Slider`][vizro.models.Slider], and [`DatePicker`][vizro.models.DatePicker].
!!! example "Filter with different selector"
=== "app.py"
@@ -162,6 +159,7 @@ Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropd
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -181,11 +179,9 @@ Currently available selectors are [`Checklist`][vizro.models.Checklist], [`Dropd
type: filter
title: My first page
```
- === "Result"
-
- [![Selector]][Selector]
- [Selector]: ../../assets/user_guides/control/control2.png
+ === "Result"
+ [![Selector]][selector]
## Further customization
@@ -220,6 +216,7 @@ Below is an advanced example where we only target one page component, and where
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -244,17 +241,19 @@ Below is an advanced example where we only target one page component, and where
controls:
- column: petal_length
targets:
- - scatter_chart
+ - scatter_chart
selector:
step: 1
type: range_slider
type: filter
title: My first page
```
- === "Result"
-
- [![Advanced]][Advanced]
- [Advanced]: ../../assets/user_guides/control/control3.png
+ === "Result"
+ [![Advanced]][advanced]
To further customize selectors, see our [how-to-guide on creating custom components](custom-components.md).
+
+[advanced]: ../../assets/user_guides/control/control3.png
+[filter]: ../../assets/user_guides/control/control1.png
+[selector]: ../../assets/user_guides/control/control2.png
diff --git a/vizro-core/docs/pages/user-guides/graph.md b/vizro-core/docs/pages/user-guides/graph.md
index 36c670997..1c3ffc8bc 100755
--- a/vizro-core/docs/pages/user-guides/graph.md
+++ b/vizro-core/docs/pages/user-guides/graph.md
@@ -6,25 +6,18 @@ The [`Graph`][vizro.models.Graph] model is the most used component in many dashb
To add a [`Graph`][vizro.models.Graph] to your page, do the following:
-1. insert the [`Graph`][vizro.models.Graph] model into the `components` argument of the
-[`Page`][vizro.models.Page] model
-2. enter any of the currently available charts of the open source library [`plotly.express`](https://plotly.com/python/plotly-express/) into the `figure` argument
+1. insert the [`Graph`][vizro.models.Graph] model into the `components` argument of the [`Page`][vizro.models.Page] model
+1. enter any of the currently available charts of the open source library [`plotly.express`](https://plotly.com/python/plotly-express/) into the `figure` argument
!!! note
+ To use the [`plotly.express`](https://plotly.com/python/plotly-express/) chart in a Vizro dashboard, you need to import it as `import vizro.plotly.express as px`. This leaves any of the [`plotly.express`](https://plotly.com/python/plotly-express/) functionality untouched yet enables _direct insertion_ into the [`Graph`][vizro.models.Graph] model _as is_.
- In order to use the [`plotly.express`](https://plotly.com/python/plotly-express/) chart in a Vizro dashboard, you need to import it as `import vizro.plotly.express as px`.
- This leaves any of the [`plotly.express`](https://plotly.com/python/plotly-express/) functionality untouched, but allows _direct insertion_ into the [`Graph`][vizro.models.Graph] model _as is_.
-
- Note also that the `plotly.express` chart needs to have a `data_frame` argument. In case you require a chart without
- a `data_frame` argument (for example, the [`imshow` chart](https://plotly.com/python/imshow/)), refer to our
- [guide on custom charts](custom-charts.md).
-
+ Note also that the `plotly.express` chart needs to have a `data_frame` argument. In case you require a chart without a `data_frame` argument (for example, the [`imshow` chart](https://plotly.com/python/imshow/)), refer to our [guide on custom charts](custom-charts.md).
## Insert Plotly chart
!!! example "Graph"
=== "app.py"
-
```{.python pycafe-link}
import vizro.models as vm
import vizro.plotly.express as px
@@ -47,25 +40,24 @@ To add a [`Graph`][vizro.models.Graph] to your page, do the following:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: scatter_matrix
- color: species
- data_frame: iris
- dimensions: ["sepal_length", "sepal_width", "petal_length", "petal_width"]
- type: graph
- title: My first page
+ - components:
+ - figure:
+ _target_: scatter_matrix
+ color: species
+ data_frame: iris
+ dimensions: [sepal_length, sepal_width, petal_length, petal_width]
+ type: graph
+ title: My first page
```
- === "Result"
- [![Graph]][Graph]
-
- [Graph]: ../../assets/user_guides/components/graph.png
+ === "Result"
+ [![Graph]][graph]
In the Python example we directly inserted the pandas DataFrame `df` into `figure=px.scatter_matrix(df, ...)`. This is [one way to supply data to a chart](data.md#supply-directly). For the YAML version, we [refer to the data source by name](data.md#reference-by-name) as `data_frame: iris`. For a full explanation of the different methods you can use to send data to your dashboard, see [our guide to using data in Vizro](data.md).
@@ -73,31 +65,24 @@ In the Python example we directly inserted the pandas DataFrame `df` into `figur
You will need to create a custom chart if you want to customize the Plotly chart beyond a function call, for example by:
-* using post-update methods like `update_layout`, `update_xaxes`, `update_traces`, or
-* by creating a custom `plotly.graph_objects.Figure()` object and manually adding traces with `add_trace`.
-
-For more details, refer to our [user guide on custom chart](custom-charts.md) and the
-[Plotly documentation on updating figures](https://plotly.com/python/creating-and-updating-figures/).
+- using post-update methods like `update_layout`, `update_xaxes`, `update_traces`, or
+- by creating a custom `plotly.graph_objects.Figure()` object and manually adding traces with `add_trace`.
+For more details, refer to our [user guide on custom chart](custom-charts.md) and the [Plotly documentation on updating figures](https://plotly.com/python/creating-and-updating-figures/).
## Add title, header, and footer
-The [`Graph`][vizro.models.Graph] accepts a `title`, `header` and `footer` argument. This is useful for providing
-context to the data being displayed, or for adding a description of the data.
+The [`Graph`][vizro.models.Graph] accepts a `title`, `header` and `footer` argument. This is useful for context on the data being displayed, or for adding a description of the data.
- **title**: Displayed as an [H3 header](https://dash.plotly.com/dash-html-components/h3), useful for summarizing the main topic or insight of the component.
- **header**: Accepts markdown text, ideal for extra descriptions, subtitles, or detailed data insights.
- **footer**: Accepts markdown text, commonly used for citing data sources, providing information on the last update, or adding disclaimers.
-
!!! note
-
- Although you can directly provide a `title` to the Plotly Express chart, we recommend using `Graph.title` for
- proper alignment with other components on the screen.
+ Although you can directly give a `title` to the Plotly Express chart, we recommend using `Graph.title` for proper alignment with other components on the screen.
!!! example "Formatted Graph"
=== "app.py"
-
```{.python pycafe-link}
import vizro.models as vm
@@ -126,31 +111,34 @@ context to the data being displayed, or for adding a description of the data.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: scatter
- x: sepal_width
- y: sepal_length
- color: species
- data_frame: iris
- title: Relationships between Sepal Width and Sepal Length
- header: |
- Each point in the scatter plot represents one of the 150 iris flowers, with colors indicating their
- types. The Setosa type is easily identifiable by its short and wide sepals.
-
- However, there is still overlap between the Versicolor and Virginica types when considering only sepal
- width and length.
- footer: |
- SOURCE: **Plotly iris data set, 2024**
- type: graph
- title: Formatted Graph
+ - components:
+ - figure:
+ _target_: scatter
+ x: sepal_width
+ y: sepal_length
+ color: species
+ data_frame: iris
+ title: Relationships between Sepal Width and Sepal Length
+ header: |
+ Each point in the scatter plot represents one of the 150 iris flowers, with colors indicating their
+ types. The Setosa type is easily identifiable by its short and wide sepals.
+
+ However, there is still overlap between the Versicolor and Virginica types when considering only sepal
+ width and length.
+ footer: |
+ SOURCE: **Plotly iris data set, 2024**
+ type: graph
+ title: Formatted Graph
```
+
=== "Result"
- [![FormattedGraph]][FormattedGraph]
+ [![FormattedGraph]][formattedgraph]
- [FormattedGraph]: ../../assets/user_guides/components/formatted_graph.png
+[formattedgraph]: ../../assets/user_guides/components/formatted_graph.png
+[graph]: ../../assets/user_guides/components/graph.png
diff --git a/vizro-core/docs/pages/user-guides/install.md b/vizro-core/docs/pages/user-guides/install.md
index 4d4c01239..6a07911e5 100644
--- a/vizro-core/docs/pages/user-guides/install.md
+++ b/vizro-core/docs/pages/user-guides/install.md
@@ -8,8 +8,8 @@ We recommend that you create a virtual environment for each Vizro project you wo
## Prerequisites to working locally
-* **Python**: Vizro supports macOS, Linux, and Windows. It works with Python 3.9 and later.
-* **Virtual environment**: You specify the version of Python to use with Vizro when you set up the virtual environment. See the following references to learn more about [Python virtual environments](https://realpython.com/python-virtual-environments-a-primer/), [Conda virtual environments](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#starting-conda) or [watch an explainer video about them](https://youtu.be/YKfAwIItO7M).
+- **Python**: Vizro supports macOS, Linux, and Windows. It works with Python 3.9 and later.
+- **Virtual environment**: You specify the version of Python to use with Vizro when you set up the virtual environment. See the following references to learn more about [Python virtual environments](https://realpython.com/python-virtual-environments-a-primer/), [Conda virtual environments](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#starting-conda) or [watch an explainer video about them](https://youtu.be/YKfAwIItO7M).
### How to create a virtual environment for your Vizro project
diff --git a/vizro-core/docs/pages/user-guides/kedro-data-catalog.md b/vizro-core/docs/pages/user-guides/kedro-data-catalog.md
index 0e2b0954e..ce4b060fa 100644
--- a/vizro-core/docs/pages/user-guides/kedro-data-catalog.md
+++ b/vizro-core/docs/pages/user-guides/kedro-data-catalog.md
@@ -3,6 +3,7 @@
This page describes how to integrate Vizro with [Kedro](https://docs.kedro.org/en/stable/index.html), an open-source Python framework to create reproducible, maintainable, and modular data science code. For Pandas datasets registered in a Kedro data catalog, Vizro provides a convenient way to visualize them.
## Installation
+
If you already have Kedro installed then you do not need to install any extra dependencies. If you do not have Kedro installed then you should run:
```bash
@@ -10,7 +11,9 @@ pip install vizro[kedro]
```
## Use datasets from the Kedro Data Catalog
+
`vizro.integrations.kedro` provides functions to help generate and process a [Kedro Data Catalog](https://docs.kedro.org/en/stable/data/index.html). Given a Kedro Data Catalog `catalog`, the general pattern to add datasets into the Vizro data manager is:
+
```python
from vizro.integrations import kedro as kedro_integration
from vizro.managers import data_manager
@@ -25,15 +28,14 @@ This imports all datasets of type [`kedro_datasets.pandas`](https://docs.kedro.o
The `catalog` variable may have been created in a number of different ways:
1. Kedro project path. Vizro exposes a helper function `vizro.integrations.kedro.catalog_from_project` to generate a `catalog` given the path to a Kedro project.
-2. [Kedro Jupyter session](https://docs.kedro.org/en/stable/notebooks_and_ipython/kedro_and_notebooks.html). This automatically exposes `catalog`.
-3. Data Catalog configuration file (`catalog.yaml`). This can create a `catalog` entirely independently of a Kedro project using [`kedro.io.DataCatalog.from_config`](https://docs.kedro.org/en/stable/kedro.io.DataCatalog.html#kedro.io.DataCatalog.from_config).
+1. [Kedro Jupyter session](https://docs.kedro.org/en/stable/notebooks_and_ipython/kedro_and_notebooks.html). This automatically exposes `catalog`.
+1. Data Catalog configuration file (`catalog.yaml`). This can create a `catalog` entirely independently of a Kedro project using [`kedro.io.DataCatalog.from_config`](https://docs.kedro.org/en/stable/kedro.io.DataCatalog.html#kedro.io.DataCatalog.from_config).
The full code for these different cases is given below.
!!! example "Import a Kedro Data Catalog into the Vizro data manager"
-
=== "app.py (Kedro project path)"
- ```py
+ ```python
from vizro.integrations import kedro as kedro_integration
from vizro.managers import data_manager
@@ -43,16 +45,18 @@ The full code for these different cases is given below.
for dataset_name, dataset in kedro_integration.datasets_from_catalog(catalog).items():
data_manager[dataset_name] = dataset
```
+
=== "app.ipynb (Kedro Jupyter session)"
- ```py
+ ```python
from vizro.managers import data_manager
for dataset_name, dataset in kedro_integration.datasets_from_catalog(catalog).items():
data_manager[dataset_name] = dataset
```
+
=== "app.py (Data Catalog configuration file)"
- ```py
+ ```python
from kedro.io import DataCatalog
import yaml
diff --git a/vizro-core/docs/pages/user-guides/layouts.md b/vizro-core/docs/pages/user-guides/layouts.md
index 8361560db..af66ec301 100644
--- a/vizro-core/docs/pages/user-guides/layouts.md
+++ b/vizro-core/docs/pages/user-guides/layouts.md
@@ -3,11 +3,10 @@
The [`Page`][vizro.models.Page] model accepts a `layout` argument that enables custom arrangement of charts and components on the screen. This guide shows how to customize the grid specifications in the [`Layout`][vizro.models.Layout].
## The default layout
-The `layout` argument of the [`Page`][vizro.models.Page] model is optional. If no layout is specified, all charts/components are automatically [**stacked vertically**](layouts.md#vertical-and-horizontal-stacking) on the page in one column.
-If you are happy with that arrangement, you can create your charts/components without providing a [`Layout`][vizro.models.Layout].
-!!! example "Default Layout"
+The `layout` argument of the [`Page`][vizro.models.Page] model is optional. If no layout is specified, all charts/components are automatically [**stacked vertically**](layouts.md#vertical-and-horizontal-stacking) on the page in one column. If you are happy with that arrangement, you can create your charts/components without providing a [`Layout`][vizro.models.Layout].
+!!! example "Default Layout"
=== "app.py"
```{.python pycafe-link}
from vizro import Vizro
@@ -23,35 +22,33 @@ If you are happy with that arrangement, you can create your charts/components wi
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- title: two_left
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ title: two_left
```
- === "Result"
- [![Layout]][Layout]
-
- [Layout]: ../../assets/user_guides/layout/two_left.png
-
+ === "Result"
+ [![Layout]][layout]
## Configure the grid
+
To customize the grid arrangement, configure the `grid` parameter of the [`Layout`][vizro.models.Layout] model.
The example below shows an example of a valid `grid`:
```python title="Basic example"
-grid = [[0, 1],
- [0, 2]]
+grid = [[0, 1], [0, 2]]
```
- The `grid` must be provided as `list[list[int]]` (for example, `grid = [[0, 1], [0, 2]]`).
@@ -64,16 +61,12 @@ grid = [[0, 1],
- The area spanned by a chart/component in the grid must be rectangular.
- The grid can be arbitrarily large, allowing arbitrarily granular control of the grid.
-
## Vertical and horizontal stacking
+
As described above, when no `Layout` is specified, components are presented **vertically** as a single-column stack. If you have three components, the default `Layout.grid` will be as follows, with three equally sized rows, each containing a component spanning the entire width:
```python title="Vertical stacking"
-grid = [
- [0],
- [1],
- [2]
- ]
+grid = [[0], [1], [2]]
```
To present components **horizontally** in one row:
@@ -89,8 +82,8 @@ This defines a single row that occupies the entire width and height, divided int
## Grid - basic example
-!!! example "Grid Arrangement - Basic Example"
+!!! example "Grid Arrangement - Basic Example"
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -109,39 +102,37 @@ This defines a single row that occupies the entire width and height, divided int
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- - text: |
- # Component 2
- type: card
- layout:
- grid: [[0, 1], [0, 2]]
- title: one_left_two_right
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ layout:
+ grid: [[0, 1], [0, 2]]
+ title: one_left_two_right
```
- === "Result"
- [![Grid]][Grid]
- [Grid]: ../../assets/user_guides/layout/one_left_two_right.png
+ === "Result"
+ [![Grid]][grid]
## Grid - advanced example
If you want to divide the grid into subgrids with finer control over these, you can use [`Containers`](container.md). See our section on [when to use `Containers` vs. `Page.layout`](container.md#when-to-use-containers) for more information.
-The `Layout` provides full control over the arrangement of top-level components within a page,
-allowing arbitrarily granular control of the grid by creating larger grids.
+The `Layout` provides full control over the arrangement of top-level components within a page, allowing arbitrarily granular control of the grid by creating larger grids.
!!! example "Grid Arrangement - Advanced Example"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -208,6 +199,7 @@ allowing arbitrarily granular control of the grid by creating larger grids.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -260,44 +252,44 @@ allowing arbitrarily granular control of the grid by creating larger grids.
grid: [[0, 1, 3, 4], [2, 2, 3, 4]]
title: Custom Layout - Advanced Example
```
- === "Result"
- [![GridAdv]][GridAdv]
- [GridAdv]: ../../assets/user_guides/layout/grid_advanced.png
+ === "Result"
+ [![GridAdv]][gridadv]
## Custom layout examples
+
Here is a reference table of example layouts:
+
one row with one component, second row with two components stacked horizontally
-| Layout needed | Grid | Code |
-|--------------------------------|----------------------------|-------------------------------------------------------------------------------------|
-| | | `layout=vm.Layout(grid=[[0]])` |
-| | | `layout=vm.Layout(grid=[[0],[1]])` |
-| | | `layout=vm.Layout(grid=[[0,1]])` |
-| | | `layout=vm.Layout(grid=[[0],[1],[2]])` or
`layout=None` | -| | | `layout=vm.Layout(grid=[[0,1],[0,2]])` |
-| | | `layout=vm.Layout(grid=[[0,0],[1,2]])` |
-| | | `layout=vm.Layout(grid=[[0,1],[2,2]])` |
-| | | `layout=vm.Layout(grid=[[0,1],[0,2],[0,3]])` |
-| | | `layout=vm.Layout(grid=[[0,1],[2,3]])` |
-| | | `layout=vm.Layout(grid=[[0,3],[1,3],[2,3]])` |
-| | | `layout=vm.Layout(grid=[[0,0,0],[1,2,3]])` |
-| | | `layout=vm.Layout(grid=[[0,1,2],[3,3,3]])` |
+| Layout needed | Grid | Code |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| | | `layout=vm.Layout(grid=[[0]])` |
+| | | `layout=vm.Layout(grid=[[0],[1]])` |
+| | | `layout=vm.Layout(grid=[[0,1]])` |
+| | | `layout=vm.Layout(grid=[[0],[1],[2]])` or
`layout=None` | +| | | `layout=vm.Layout(grid=[[0,1],[0,2]])` |
+| | | `layout=vm.Layout(grid=[[0,0],[1,2]])` |
+| | | `layout=vm.Layout(grid=[[0,1],[2,2]])` |
+| | | `layout=vm.Layout(grid=[[0,1],[0,2],[0,3]])` |
+| | | `layout=vm.Layout(grid=[[0,1],[2,3]])` |
+| | | `layout=vm.Layout(grid=[[0,3],[1,3],[2,3]])` |
+| | | `layout=vm.Layout(grid=[[0,0,0],[1,2,3]])` |
+| | | `layout=vm.Layout(grid=[[0,1,2],[3,3,3]])` |
## Add empty sections to the grid
+
One approach to organize the dashboard's layout involves integrating empty sections by specifying `-1` within the grid layout.
```python title="Example"
-grid = [[0, 1, -1],
- [0, 2, -1]]
+grid = [[0, 1, -1], [0, 2, -1]]
```
!!! example "Adding Empty Spaces"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -316,38 +308,38 @@ grid = [[0, 1, -1],
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- - text: |
- # Component 2
- type: card
- layout:
- grid: [[0, 1, -1], [0, 2, -1]]
- title: Adding empty spaces
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ layout:
+ grid: [[0, 1, -1], [0, 2, -1]]
+ title: Adding empty spaces
```
- === "Result"
- [![GridEmpty]][GridEmpty]
- [GridEmpty]: ../../assets/user_guides/layout/layout_empty_spaces.png
+ === "Result"
+ [![GridEmpty]][gridempty]
## Control the scroll behavior
+
By default, the grid fits all charts/components on the screen. This can lead to distortions such that the chart/component looks squashed. To control the scroll behavior, you can specify the following:
- `row_min_height`: Sets a chart/component's minimum height. Defaults to 0px.
- `col_min_width`: Sets a chart/component's minimum width. Defaults to 0px.
!!! example "Activate Scrolling"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -371,59 +363,63 @@ By default, the grid fits all charts/components on the screen. This can lead to
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- - text: |
- # Component 2
- type: card
- - text: |
- # Component 2
- type: card
- - text: |
- # Component 4
- type: card
- - text: |
- # Component 5
- type: card
- - text: |
- # Component 6
- type: card
- - text: |
- # Component 7
- type: card
- layout:
- grid: [[0], [1], [2], [3], [4], [5], [6], [7]]
- row_min_height: 240px
- title: Activate scrolling
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ - text: |
+ # Component 4
+ type: card
+ - text: |
+ # Component 5
+ type: card
+ - text: |
+ # Component 6
+ type: card
+ - text: |
+ # Component 7
+ type: card
+ layout:
+ grid: [[0], [1], [2], [3], [4], [5], [6], [7]]
+ row_min_height: 240px
+ title: Activate scrolling
```
- === "Result"
- [![GridScroll]][GridScroll]
-
- [GridScroll]: ../../assets/user_guides/layout/grid_scroll.png
+ === "Result"
+ [![GridScroll]][gridscroll]
## Further customization
-For further customization, such as changing the gap between row and column, refer to the
-documentation of the [`Layout`][vizro.models.Layout] model.
+
+For further customization, such as changing the gap between row and column, refer to the documentation of the [`Layout`][vizro.models.Layout] model.
## Alternative layout approaches
+
In general, any arbitrarily granular layout can already be achieved using [`Page.layout`](layouts.md) alone and is our recommended approach if you want to arrange components on a page with consistent row and/or column spacing.
!!! note "Alternative layout approaches: `Tabs` and `Containers`"
-
- [`Tabs`][vizro.models.Tabs] and [`Containers`][vizro.models.Container] provide an alternative approach to customize your page layout.
- For example, if you want to have more granular control and break the overall page grid into subgrids, see our [user guide on Containers](container.md).
+ [`Tabs`][vizro.models.Tabs] and [`Containers`][vizro.models.Container] offer an alternative approach to customize your page layout. For example, if you want to have more granular control and break the overall page grid into subgrids, see our [user guide on Containers](container.md).
If you want to display multiple containers on one page by putting them into the same screen space, and letting the user switch between them, see our [user guide on Tabs](tabs.md).
{ width="500" }
+
+[grid]: ../../assets/user_guides/layout/one_left_two_right.png
+[gridadv]: ../../assets/user_guides/layout/grid_advanced.png
+[gridempty]: ../../assets/user_guides/layout/layout_empty_spaces.png
+[gridscroll]: ../../assets/user_guides/layout/grid_scroll.png
+[layout]: ../../assets/user_guides/layout/two_left.png
diff --git a/vizro-core/docs/pages/user-guides/navigation.md b/vizro-core/docs/pages/user-guides/navigation.md
index 41c6bb9dc..75a661470 100644
--- a/vizro-core/docs/pages/user-guides/navigation.md
+++ b/vizro-core/docs/pages/user-guides/navigation.md
@@ -2,8 +2,7 @@
This guide shows you how to use and customize the navigation that appears on the left of your dashboard.
-The [`Dashboard`][vizro.models.Dashboard] model accepts a `navigation` argument, where you can enter a [`Navigation`][vizro.models.Navigation] model. This enables you to group pages together and customize how they appear in your navigation.
-The dashboard includes a collapsible side panel that users can minimize or expand by a button click. The collapse button, located in the top right corner of the side panel, is visible by default for user convenience.
+The [`Dashboard`][vizro.models.Dashboard] model accepts a `navigation` argument, where you can enter a [`Navigation`][vizro.models.Navigation] model. This enables you to group pages together and customize how they appear in your navigation. The dashboard includes a collapsible side panel that users can minimize or expand by a button click. The collapse button, located in the top right corner of the side panel, is visible by default for user convenience.
## Use the default navigation
@@ -56,8 +55,8 @@ By default, if the `navigation` argument is not specified, Vizro creates a navig
type: graph
title: My first page
- components:
- - text: My text here
- type: card
+ - text: My text here
+ type: card
title: My second page
- components:
- figure:
@@ -69,10 +68,9 @@ By default, if the `navigation` argument is not specified, Vizro creates a navig
type: graph
title: My third page
```
- === "Result"
- [![DefaultNavigation]][DefaultNavigation]
- [DefaultNavigation]: ../../assets/user_guides/navigation/default_navigation.png
+ === "Result"
+ [![DefaultNavigation]][defaultnavigation]
## Include a subset of pages
@@ -132,17 +130,15 @@ To include only some of your dashboard pages in your navigation then list them i
- My first page
- My second page
```
- === "Result"
- [![OnlySomePages]][OnlySomePages]
- [OnlySomePages]: ../../assets/user_guides/navigation/only_some_pages.png
+ === "Result"
+ [![OnlySomePages]][onlysomepages]
## Group pages
You can also group your pages together by specifying `pages` as a dictionary:
!!! example "Grouping pages"
-
=== "snippet.py"
```py
# page_1, page_2, page_3 defined as in default example
@@ -154,7 +150,6 @@ You can also group your pages together by specifying `pages` as a dictionary:
```
=== "app.py"
-
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -187,6 +182,7 @@ You can also group your pages together by specifying `pages` as a dictionary:
)
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -200,18 +196,15 @@ You can also group your pages together by specifying `pages` as a dictionary:
Group B:
- My third page
```
- === "Result"
- [![GroupedNavigation]][GroupedNavigation]
-
- [GroupedNavigation]: ../../assets/user_guides/navigation/grouped_navigation.png
+ === "Result"
+ [![GroupedNavigation]][groupednavigation]
## Use a navigation bar with icons
Another way to group together pages in the navigation is to use a [`NavBar`][vizro.models.NavBar] with icons. The simplest way to use this is to change the `nav_selector` specified in [`Navigation`][vizro.models.Navigation]:
!!! example "Using `NavBar`"
-
=== "snippet.py"
```py
# page_1, page_2, page_3 defined as in default example
@@ -223,8 +216,8 @@ Another way to group together pages in the navigation is to use a [`NavBar`][viz
)
Vizro().build(dashboard).run()
```
- === "app.py"
+ === "app.py"
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -276,14 +269,11 @@ Another way to group together pages in the navigation is to use a [`NavBar`][viz
nav_selector:
type: nav_bar
```
- === "Result"
- [![NavBar]][NavBar]
-
- [NavBar]: ../../assets/user_guides/navigation/nav_bar.png
+ === "Result"
+ [![NavBar]][navbar]
-Here, the first level of the navigation hierarchy ("Group A" and "Group B") is represented by an icon in a navigation bar, and the second level of the navigation (the pages) is represented by an accordion.
-By default, the set of icons used are the [`filter` icons from the Google Material icons library](https://fonts.google.com/icons?icon.query=filter). The icon label ("Group A" and "Group B") appears as a tooltip on hovering over the icon.
+Here, the first level of the navigation hierarchy ("Group A" and "Group B") is represented by an icon in a navigation bar, and the second level of the navigation (the pages) is represented by an accordion. By default, the set of icons used are the [`filter` icons from the Google Material icons library](https://fonts.google.com/icons?icon.query=filter). The icon label ("Group A" and "Group B") appears as a tooltip on hovering over the icon.
## Customize the navigation bar
@@ -314,7 +304,6 @@ The same configuration for [grouping pages](#group-pages) applies inside a `NavL
```
=== "app.py"
-
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -375,10 +364,9 @@ The same configuration for [grouping pages](#group-pages) applies inside a `NavL
Group B:
- My third page
```
- === "Result"
- [![AccordionInsideNavBar]][AccordionInsideNavBar]
- [AccordionInsideNavBar]: ../../assets/user_guides/navigation/accordion_inside_nav_bar.png
+ === "Result"
+ [![AccordionInsideNavBar]][accordioninsidenavbar]
You can alter the icons used by specifying the name of the icon in the [Google Material icons library](https://fonts.google.com/icons):
@@ -402,8 +390,8 @@ You can alter the icons used by specifying the name of the icon in the [Google M
),
)
```
- === "app.py"
+ === "app.py"
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -468,7 +456,13 @@ You can alter the icons used by specifying the name of the icon in the [Google M
pages:
- My third page
```
- === "Result"
- [![CustomIcons]][CustomIcons]
- [CustomIcons]: ../../assets/user_guides/navigation/custom_icons.png
+ === "Result"
+ [![CustomIcons]][customicons]
+
+[accordioninsidenavbar]: ../../assets/user_guides/navigation/accordion_inside_nav_bar.png
+[customicons]: ../../assets/user_guides/navigation/custom_icons.png
+[defaultnavigation]: ../../assets/user_guides/navigation/default_navigation.png
+[groupednavigation]: ../../assets/user_guides/navigation/grouped_navigation.png
+[navbar]: ../../assets/user_guides/navigation/nav_bar.png
+[onlysomepages]: ../../assets/user_guides/navigation/only_some_pages.png
diff --git a/vizro-core/docs/pages/user-guides/pages.md b/vizro-core/docs/pages/user-guides/pages.md
index 7ae944e9b..71e01e9f9 100644
--- a/vizro-core/docs/pages/user-guides/pages.md
+++ b/vizro-core/docs/pages/user-guides/pages.md
@@ -1,7 +1,6 @@
# How to use pages
-This guide shows you how to add pages to your dashboard and customize the URL paths if needed.
-A [`Page`][vizro.models.Page] lets you place and arrange your dashboard content (for example, chart/components, tables, and text)
-and configure your dashboard interactions (such as filters and parameters).
+
+This guide shows you how to add pages to your dashboard and customize the URL paths if needed. A [`Page`][vizro.models.Page] lets you place and arrange your dashboard content (for example, chart/components, tables, and text) and configure your dashboard interactions (such as filters and parameters).
The [`Dashboard`][vizro.models.Dashboard] model accepts the `pages` argument, where you can insert your [`Page`][vizro.models.Page].
@@ -10,19 +9,19 @@ The [`Dashboard`][vizro.models.Dashboard] model accepts the `pages` argument, wh
A [`Page`][vizro.models.Page] is split up into four main containers:
1. The **navigation container** where you can customize your `navigation` (see [Dashboard](dashboard.md) and [Navigation](navigation.md) for more information). Note that the navigation container needs to be configured via the Dashboard.
-2. The **control container** where you can add your `controls` (see [Filters](filters.md) or [Parameters](parameters.md)) to interact with the dashboard
-3. The **page header** that contains the page title and the theme toggle switch button
-4. The **component container** where you can add your [components](components.md) to visualize your data
+1. The **control container** where you can add your `controls` (see [Filters](filters.md) or [Parameters](parameters.md)) to interact with the dashboard
+1. The **page header** that contains the page title and the theme toggle switch button
+1. The **component container** where you can add your [components](components.md) to visualize your data
To create and add a page to your dashboard, do the following steps:
1. Set a `title` for your [`Page`][vizro.models.Page]
-2. Configure your `components`, see our guide on the [various options](components.md)
-3. (optional) Configure your `controls` , see our guides on [Filters](filters.md) and [Parameters](parameters.md)
-4. (optional) Configure your `layout` , see our guide on [Layouts](layouts.md)
-5. (optional) Give a `description` of your `Page` to the app's [meta tags](https://metatags.io/)
+1. Configure your `components`, see our guide on the [various options](components.md)
+1. (optional) Configure your `controls` , see our guides on [Filters](filters.md) and [Parameters](parameters.md)
+1. (optional) Configure your `layout` , see our guide on [Layouts](layouts.md)
+1. (optional) Give a `description` of your `Page` to the app's [meta tags](https://metatags.io/)
!!! example "Page"
=== "app.py"
@@ -51,51 +50,47 @@ To create and add a page to your dashboard, do the following steps:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: sunburst
- path: ['continent', 'country']
- values: pop
- color: lifeExp
- data_frame: gapminder
- id: sunburst
- type: graph
- controls:
- - column: continent
- targets:
- - sunburst
- type: filter
- - selector:
- options: ['lifeExp', 'pop']
- title: Color
- type: radio_items
- targets:
- - sunburst.color
- type: parameter
- title: Page Title
- description: "Longer description of the page content"
+ - components:
+ - figure:
+ _target_: sunburst
+ path: [continent, country]
+ values: pop
+ color: lifeExp
+ data_frame: gapminder
+ id: sunburst
+ type: graph
+ controls:
+ - column: continent
+ targets: [sunburst]
+ type: filter
+ - selector:
+ options: [lifeExp, pop]
+ title: Color
+ type: radio_items
+ targets: [sunburst.color]
+ type: parameter
+ title: Page Title
+ description: Longer description of the page content
```
- === "Result"
- [![Page]][Page]
- [Page]: ../../assets/user_guides/pages/page_sunburst.png
+ === "Result"
+ [![Page]][page]
An accordion page selector is automatically added to your dashboard in the top-left of the control container for through the different pages. It will not be added if your dashboard consists of only one page.
You can additionally navigate through the different pages by going directly to the relevant page URL (more details in next section).
-
## Customize the page URL
-By default, the page URL is automatically generated based on the `id` of the page. For example, if `id="This is my first page"`
-the generated page URL will be `path=this-is-my-first-page`. You can then access the page via `localhost:/this-is-my-first-page`.
-Note that the page `id` defaults to be the same as the page `title` if not set.
-If you have multiple pages with the same `title` then you must assign a unique `id`.
+By default, the page URL is automatically generated based on the `id` of the page. For example, if `id="This is my first page"` the generated page URL will be `path=this-is-my-first-page`. You can then access the page via `localhost:/this-is-my-first-page`.
+
+Note that the page `id` defaults to be the same as the page `title` if not set. If you have multiple pages with the same `title` then you must assign a unique `id`.
The first page always has the URL prefix `/` assigned. A custom URL can, therefore, not be created for the first page.
@@ -137,39 +132,40 @@ To customize the page URL, pass a valid URL name to the `path` argument of [`Pag
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- Commodi repudiandae consequuntur voluptatum.
- type: card
- title: Page 1
- - components:
- - figure:
- _target_: sunburst
- path: ['continent', 'country']
- values: pop
- color: lifeExp
- data_frame: gapminder
- id: sunburst
- type: graph
- controls:
- - column: continent
- targets:
- - sunburst
- type: filter
- - selector:
- options: ['lifeExp', 'pop']
- title: Color
- type: radio_items
- targets:
- - sunburst.color
- type: parameter
- title: Page 2
- path: my-custom-url
+ - components:
+ - text: |
+ Commodi repudiandae consequuntur voluptatum.
+ type: card
+ title: Page 1
+ - components:
+ - figure:
+ _target_: sunburst
+ path: [continent, country]
+ values: pop
+ color: lifeExp
+ data_frame: gapminder
+ id: sunburst
+ type: graph
+ controls:
+ - column: continent
+ targets: [sunburst]
+ type: filter
+ - selector:
+ options: [lifeExp, pop]
+ title: Color
+ type: radio_items
+ targets: [sunburst.color]
+ type: parameter
+ title: Page 2
+ path: my-custom-url
```
You can now access the first page via `localhost:/` and the second page via `localhost:/my-custom-url`.
+
+[page]: ../../assets/user_guides/pages/page_sunburst.png
diff --git a/vizro-core/docs/pages/user-guides/parameters.md b/vizro-core/docs/pages/user-guides/parameters.md
index bb39a7a0c..c82707d4a 100644
--- a/vizro-core/docs/pages/user-guides/parameters.md
+++ b/vizro-core/docs/pages/user-guides/parameters.md
@@ -9,8 +9,8 @@ The [`Page`][vizro.models.Page] model accepts the `controls` argument, where you
To add a parameter to your page, do the following:
1. add the [`Parameter`][vizro.models.Parameter] model into the `controls` argument of the [`Page`][vizro.models.Page] model.
-2. add the `targets` argument
-3. add a selector model to the `selector` argument.
+1. add the `targets` argument
+1. add a selector model to the `selector` argument.
In the `targets` argument, you can specify the component and function argument that the parameter should be applied to in the form of `.` (for example, `scatter_chart.title`).
@@ -48,6 +48,7 @@ Unlike for the [`Filter`][vizro.models.Filter] model, you also have to configure
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -64,18 +65,17 @@ Unlike for the [`Filter`][vizro.models.Filter] model, you also have to configure
type: graph
controls:
- selector:
- options: ["My scatter chart", "A better title!", "Another title..."]
- multi: False
+ options: [My scatter chart, A better title!, Another title...]
+ multi: false
type: dropdown
targets:
- scatter_chart.title
type: parameter
title: My first page
```
- === "Result"
- [![Parameter]][Parameter]
- [Parameter]: ../../assets/user_guides/control/control4.png
+ === "Result"
+ [![Parameter]][parameter]
If you would like to pass `None` as a parameter and make a parameter optional, you can specify the string `"NONE"` in the `options` or `value` field.
@@ -133,6 +133,7 @@ If you want to change nested parameters, you can specify the `targets` argument
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -146,7 +147,7 @@ If you want to change nested parameters, you can specify the `targets` argument
y: sepal_length
size: petal_length
color: species
- color_discrete_map: {"setosa": "#00b4ff", "versicolor": "#ff9222"}
+ color_discrete_map: {setosa: '#00b4ff', versicolor: '#ff9222'}
id: scatter_chart
type: graph
- figure:
@@ -155,23 +156,22 @@ If you want to change nested parameters, you can specify the `targets` argument
x: sepal_width
y: sepal_length
color: species
- color_discrete_map: {"setosa": "#00b4ff", "versicolor": "#ff9222"}
+ color_discrete_map: {setosa: '#00b4ff', versicolor: '#ff9222'}
id: bar_chart
type: graph
controls:
- selector:
- options: ["#ff5267", "#3949ab"]
+ options: ['#ff5267', '#3949ab']
value: #3949ab
- multi: False
+ multi: false
type: dropdown
- targets: ["scatter_chart.color_discrete_map.virginica", "bar_chart.color_discrete_map.virginica"]
+ targets: [scatter_chart.color_discrete_map.virginica, bar_chart.color_discrete_map.virginica]
type: parameter
title: My first page
```
- === "Result"
- [![Nested]][Nested]
- [Nested]: ../../assets/user_guides/control/control5.png
+ === "Result"
+ [![Nested]][nested]
In the above example, the object passed to the function argument `color_discrete_map` is a dictionary which maps the different flower species to fixed colors (for example, `{"virginica":"blue"}`). In this case, only the value `blue` should be changed instead of the entire dictionary. This can be achieved by specifying a target as `scatter.color_discrete_map.virginica`.
@@ -180,3 +180,6 @@ Note that in the above example, one parameter affects multiple targets.
## Dynamic data parameters
If you use [dynamic data](data.md/#dynamic-data) that can be updated while the dashboard is running then you can pass parameters to the dynamic data function to alter the data loaded into your dashboard. For detailed instructions, refer to the section on [parametrized data loading](data.md/#parametrize-data-loading).
+
+[nested]: ../../assets/user_guides/control/control5.png
+[parameter]: ../../assets/user_guides/control/control4.png
diff --git a/vizro-core/docs/pages/user-guides/run.md b/vizro-core/docs/pages/user-guides/run.md
index df52e8c14..028eb5027 100644
--- a/vizro-core/docs/pages/user-guides/run.md
+++ b/vizro-core/docs/pages/user-guides/run.md
@@ -15,7 +15,6 @@ Most of our examples have a link below the code, [Run and edit this code in PyCa
You can use [PyCafe](https://py.cafe/snippet/vizro/v1) snippet mode to experiment with your own Vizro dashboards by dropping code into a new project.
-
## Default built-in Flask development server
!!! example "Default built-in Flask development server"
@@ -38,9 +37,10 @@ You can use [PyCafe](https://py.cafe/snippet/vizro/v1) snippet mode to experimen
Vizro().build(dashboard).run()
```
+
1. create a Python file named `app.py`.
-2. type the command `python app.py` into your terminal.
-3. information below will be displayed in your terminal, go to [http://127.0.0.1:8050/](http://127.0.0.1:8050/).
+1. type the command `python app.py` into your terminal.
+1. information below will be displayed in your terminal, go to [http://127.0.0.1:8050/](http://127.0.0.1:8050/).
```
Dash is running on http://127.0.0.1:8050/
@@ -51,8 +51,7 @@ INFO:werkzeug:WARNING: This is a development server. Do not use it in a producti
```
!!! warning "In production"
-
- As per the above warning message, which is [further explained in the Flask documentation](https://flask.palletsprojects.com/en/3.0.x/deploying/), the Flask development server is intended for use only during local development and **should not** be used when deploying to production. Instead, you should instead use a production-ready solution such as [Gunicorn](#gunicorn).
+ The above warning message is [further explained in the Flask documentation](https://flask.palletsprojects.com/en/3.0.x/deploying/). The Flask development server is intended for use only during local development and **should not** be used when deploying to production. Instead, you should instead use a production-ready solution such as [Gunicorn](#gunicorn).
### Automatic reloading and debugging
@@ -64,11 +63,11 @@ Setting `debug=True` enables [Dash Dev Tools](https://dash.plotly.com/devtools).
In addition, some errors generated at run time can also be viewed via the browser console (for example in `Chrome` see `View > Developer > Developer Tools > Console`).
-
## Jupyter
+
The dashboard application can be launched in a Jupyter environment in `inline`, `external`, and `jupyterlab` mode.
-!!! example "Run in a Jupyter Notebook in inline mode"
+!!! example "Run in a Jupyter Notebook in inline mode"
=== "app.ipynb"
```py linenums="1"
from vizro import Vizro
@@ -87,16 +86,16 @@ The dashboard application can be launched in a Jupyter environment in `inline`,
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run(jupyter_mode="external")
```
+
- by default, the mode is set to `inline` in `run()` and the dashboard will be displayed inside your Jupyter environment.
- you can specify `jupyter_mode="external"` and a link will be displayed to direct you to the localhost where the dashboard is running.
- you can use tab mode by `jupyter_mode="tab"` to automatically open the app in a new browser
!!! note "Reloading and debugging"
-
Code reloading and hot reloading do not work within a Jupyter Notebook. Instead, there are two methods to reload the dashboard:
- * Restart the Jupyter kernel and re-run your notebook.
- * Add a cell containing `from vizro import Vizro; Vizro._reset()` to the top of your notebook and re-run it. With this method, there is no need to restart the Jupyter kernel.
+ - Restart the Jupyter kernel and re-run your notebook.
+ - Add a cell containing `from vizro import Vizro; Vizro._reset()` to the top of your notebook and re-run it. With this method, there is no need to restart the Jupyter kernel.
## Gunicorn
@@ -126,17 +125,18 @@ The dashboard application can be launched in a Jupyter environment in `inline`,
```
1. The Vizro `app` object is a WSGI application that exposes the underlying Flask app; this will be used by Gunicorn.
- 2. Enable the same app to still be run using the built-in Flask server with `python app.py` for development purposes.
+ 1. Enable the same app to still be run using the built-in Flask server with `python app.py` for development purposes.
To run using Gunicorn with four worker processes, execute
+
```bash
gunicorn app:app --workers 4
```
+
in the command line. For more Gunicorn configuration options, refer to [Gunicorn documentation](https://docs.gunicorn.org/).
!!! warning "In production"
-
- If your dashboard uses [dynamic data](data.md#dynamic-data) that can be refreshed while the dashboard is running then you should [configure your data manager cache](data.md#configure-cache) to use a backend that supports multiple processes.
+ If your dashboard uses [dynamic data](data.md#dynamic-data) that can be refreshed while the dashboard is running then you should [configure your data manager cache](data.md#configure-cache) to use a back end that supports multiple processes.
## Deployment
@@ -149,6 +149,6 @@ Internally, `app = Vizro()` contains a Flask app in `app.dash.server`. However,
[`Vizro`][vizro.Vizro] accepts `**kwargs` that are passed through to `Dash`. This enables you to configure the underlying Dash app using the same [arguments that are available](https://dash.plotly.com/reference#dash.dash) in `Dash`. For example, in a deployment context, these arguments may be useful:
-- `url_base_pathname`: serve your Vizro app at a specific path rather than at the domain root. For example, if you host your dashboard at http://www.example.com/my_dashboard/ then you would set `url_base_pathname="/my_dashboard/"` or an environment variable `DASH_URL_BASE_PATHNAME="/my_dashboard/"`.
+- `url_base_pathname`: serve your Vizro app at a specific path rather than at the domain root. For example, if you host your dashboard at `http://www.example.com/my_dashboard/` then you would set `url_base_pathname="/my_dashboard/"` or an environment variable `DASH_URL_BASE_PATHNAME="/my_dashboard/"`.
- `serve_locally`: set to `False` to [serve Dash component libraries from a Content Delivery Network (CDN)](https://dash.plotly.com/external-resources#serving-dash's-component-libraries-locally-or-from-a-cdn), which reduces load on the server and can improve performance. Vizro uses [jsDeliver](https://www.jsdelivr.com/) as a CDN for CSS and JavaScript sources.
- `assets_external_path`: when `serve_locally=False`, you can also set `assets_external_path` or an environment variable `DASH_ASSETS_EXTERNAL_PATH` to [serve your own assets from a CDN](https://dash.plotly.com/external-resources#load-assets-from-a-folder-hosted-on-a-cdn).
diff --git a/vizro-core/docs/pages/user-guides/selectors.md b/vizro-core/docs/pages/user-guides/selectors.md
index 10481d2ba..a1bd4be20 100644
--- a/vizro-core/docs/pages/user-guides/selectors.md
+++ b/vizro-core/docs/pages/user-guides/selectors.md
@@ -6,10 +6,7 @@ The [`Filter`][vizro.models.Filter] or the [`Parameter`][vizro.models.Parameter]
## Categorical selectors
-Within the categorical selectors, a clear distinction exists between multi-option and single-option selectors.
-For instance, the [`Checklist`][vizro.models.Checklist] functions as a multi-option selector by default while
-the [`RadioItem`][vizro.models.RadioItems] serves as a single-option selector by default. However, the
-[`Dropdown`][vizro.models.Dropdown] can function as both a multi-option or single-option selector.
+Within the categorical selectors, a clear distinction exists between multi-option and single-option selectors. For instance, the [`Checklist`][vizro.models.Checklist] functions as a multi-option selector by default while the [`RadioItem`][vizro.models.RadioItems] serves as a single-option selector by default. However, the [`Dropdown`][vizro.models.Dropdown] can function as both a multi-option or single-option selector.
For more information, refer to the API reference of the selector, or the documentation of its underlying Dash component:
@@ -18,15 +15,12 @@ For more information, refer to the API reference of the selector, or the documen
- [`RadioItems`][vizro.models.RadioItems] based on [`dcc.RadioItems`](https://dash.plotly.com/dash-core-components/radioitems)
!!! note
-
- When configuring the `options` of the categorical selectors, you can either provide:
+ When configuring the `options` of the categorical selectors, you can either give:
- a list of values `options = ['Value A', 'Value B', 'Value C']`
- or a dictionary of label-value mappings `options=[{'label': 'True', 'value': True}, {'label': 'False', 'value': False}]`
- The later is required if you want to provide different display labels to your option values or in case you want to
- provide boolean values as options. In this case, you need to provide a string label for your boolean values as
- boolean values cannot be displayed properly as labels in the underlying Dash components.
+ The later is required if you want to provide different display labels to your option values or in case you want to provide boolean values as options. In this case, you need to provide a string label for your boolean values as boolean values cannot be displayed properly as labels in the underlying Dash components.
## Numerical selectors
@@ -36,11 +30,7 @@ For more information, refer to the API reference of the selector, or the documen
- [`RangeSlider`][vizro.models.RangeSlider] based on [`dcc.RangeSlider`](https://dash.plotly.com/dash-core-components/rangeslider)
!!! note
-
- When configuring the [`Slider`][vizro.models.Slider] and the [`RangeSlider`][vizro.models.RangeSlider] with float values, and using `step` with an integer value, you may notice
- unexpected behavior, such as the drag value being outside its indicated marks.
- To our knowledge, this is a current bug in the underlying [`dcc.Slider`](https://dash.plotly.com/dash-core-components/slider) and
- [`dcc.RangeSlider`](https://dash.plotly.com/dash-core-components/rangeslider) component, which you can circumvent by adapting the `step` size accordingly.
+ When configuring the [`Slider`][vizro.models.Slider] and the [`RangeSlider`][vizro.models.RangeSlider] with float values, and using `step` with an integer value, you may notice unexpected behavior, such as the drag value being outside its indicated marks. To our knowledge, this is a current bug in the underlying [`dcc.Slider`](https://dash.plotly.com/dash-core-components/slider) and [`dcc.RangeSlider`](https://dash.plotly.com/dash-core-components/rangeslider) component, which you can circumvent by adapting the `step` size as needed.
## Temporal selectors
@@ -49,7 +39,6 @@ For more information, refer to the API reference of the selector, or the documen
- [`DatePicker`][vizro.models.DatePicker] based on [`dmc.DateRangePicker`](https://www.dash-mantine-components.com/components/datepicker#daterangepicker) and [`dmc.DatePicker`](https://www.dash-mantine-components.com/components/datepicker)
!!! note
-
When the [`DatePicker`][vizro.models.DatePicker] is configured with `range=True` (the default), the underlying component is `dmc.DateRangePicker`. When `range=False` the underlying component is `dmc.DatePicker`.
When configuring the [`DatePicker`][vizro.models.DatePicker] make sure to provide your dates for `min`, `max` and `value` arguments in `"yyyy-mm-dd"` format or as `datetime` type (for example, `datetime.datetime(2024, 01, 01)`).
diff --git a/vizro-core/docs/pages/user-guides/table.md b/vizro-core/docs/pages/user-guides/table.md
index 19197c465..80e8e53dc 100755
--- a/vizro-core/docs/pages/user-guides/table.md
+++ b/vizro-core/docs/pages/user-guides/table.md
@@ -2,46 +2,32 @@
This guide shows you how to visualize tables in Vizro.
-There are two ways to visualize tables in Vizro, using either [AG Grid](#ag-grid) or [Dash DataTable](#dash-datatable).
-In general, [AG Grid](#ag-grid) is Vizro's recommended table implementation, but sometimes it may make sense to use the [Dash DataTable](#dash-datatable) instead.
+There are two ways to visualize tables in Vizro, using either [AG Grid](#ag-grid) or [Dash DataTable](#dash-datatable). In general, [AG Grid](#ag-grid) is Vizro's recommended table implementation, but sometimes it may make sense to use the [Dash DataTable](#dash-datatable) instead.
## Choose between AG Grid and Dash DataTable
-Vizro offers two models - the [`AgGrid`][vizro.models.AgGrid] model and the [`Table`][vizro.models.Table] model - for the above two approaches respectively.
-They both visualize tabular data in similar ways.
+Vizro offers two models - the [`AgGrid`][vizro.models.AgGrid] model and the [`Table`][vizro.models.Table] model - for the above two approaches respectively. They both visualize tabular data in similar ways.
-The main difference between the two is that the [`AgGrid`][vizro.models.AgGrid] model is based on Plotly's [Dash AG Grid](https://dash.plotly.com/dash-ag-grid) component,
-while the [`Table`][vizro.models.Table] model is based on the [Dash DataTable](https://dash.plotly.com/datatable) component.
-
-Both approaches have similar base features, and are configurable in similar ways. However, the AG Grid offers more advanced features out-of-the-box, is more customizable
-and also ships a powerful enterprise version. This is why it is Vizro's recommended table implementation. At the same time, the Dash DataTable can be used if developers are
-already familiar with it, or if some custom functionality is easier to implement using the Dash DataTable.
+The main difference between the two is that the [`AgGrid`][vizro.models.AgGrid] model is based on Plotly's [Dash AG Grid](https://dash.plotly.com/dash-ag-grid) component, while the [`Table`][vizro.models.Table] model is based on the [Dash DataTable](https://dash.plotly.com/datatable) component.
+Both approaches have similar base features, and are configurable in similar ways. However, the AG Grid offers more advanced features out-of-the-box, is more customizable and also ships a powerful enterprise version. This is why it is Vizro's recommended table implementation. At the same time, the Dash DataTable can be used if developers are already familiar with it, or if some custom functionality is easier to implement using the Dash DataTable.
## AG Grid
-[AG Grid](https://www.ag-grid.com/) is an interactive table/grid component designed for viewing, editing, and exploring large datasets. It
-is Vizro's recommended table implementation.
+[AG Grid](https://www.ag-grid.com/) is an interactive table/grid component designed for viewing, editing, and exploring large datasets. It is Vizro's recommended table implementation.
-The Vizro [`AgGrid`][vizro.models.AgGrid] model is based on the [Dash AG Grid](https://dash.plotly.com/dash-ag-grid), which is in turn based the
-original [Javascript implementation](https://www.ag-grid.com/).
+The Vizro [`AgGrid`][vizro.models.AgGrid] model is based on the [Dash AG Grid](https://dash.plotly.com/dash-ag-grid), which is in turn based the original [Javascript implementation](https://www.ag-grid.com/).
### Basic usage
To add a [`AgGrid`][vizro.models.AgGrid] to your page, do the following:
-1. Insert the [`AgGrid`][vizro.models.AgGrid] model into the `components` argument of the
-[`Page`][vizro.models.Page] model.
-2. Enter the `dash_ag_grid` function under the `figure` argument (imported via `from vizro.tables import dash_ag_grid`).
-
-The Vizro version of this AG Grid differs in one way from the original Dash AG Grid: it requires the user to pass a pandas DataFrame as the source of data.
-As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`. Most other [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments.
-Note that some defaults are set for some arguments (for example, for `columnDefs`) to help with styling and usability.
-Sometimes a parameter may not work because it requires a callback to function. In that case you can try [creating a custom AG Grid callable](custom-tables.md).
+1. Insert the [`AgGrid`][vizro.models.AgGrid] model into the `components` argument of the [`Page`][vizro.models.Page] model.
+1. Enter the `dash_ag_grid` function under the `figure` argument (imported via `from vizro.tables import dash_ag_grid`).
+The Vizro version of this AG Grid differs in one way from the original Dash AG Grid: it requires the user to pass a pandas DataFrame as the source of data. As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`. Most other [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments. Note that some defaults are set for some arguments (for example, for `columnDefs`) to help with styling and usability. Sometimes a parameter may not work because it requires a callback to function. In that case you can try [creating a custom AG Grid callable](custom-tables.md).
!!! example "Basic Dash AG Grid"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -59,29 +45,28 @@ Sometimes a parameter may not work because it requires a callback to function. I
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - figure:
- _target_: dash_ag_grid
- data_frame: gapminder
- type: ag_grid
- title: Default Dash AG Grid
+ - components:
+ - figure:
+ _target_: dash_ag_grid
+ data_frame: gapminder
+ type: ag_grid
+ title: Default Dash AG Grid
```
- === "Result"
- [![AGGrid]][AGGrid]
- [AGGrid]: ../../assets/user_guides/table/aggrid.png
+ === "Result"
+ [![AGGrid]][aggrid]
### Enable pagination
-Pagination is a visual alternative to using vertical scroll. It can also improve loading time if you have many rows.
-You can turn it on by setting `dashGridOptions={"pagination": True}`.
-!!! example "Basic Dash AG Grid"
+Pagination is a visual alternative to using vertical scroll. It can also improve loading time if you have many rows. You can turn it on by setting `dashGridOptions={"pagination": True}`.
+!!! example "Basic Dash AG Grid"
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -99,37 +84,34 @@ You can turn it on by setting `dashGridOptions={"pagination": True}`.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - figure:
- _target_: dash_ag_grid
- data_frame: gapminder
- dashGridOptions:
- pagination: true
- type: ag_grid
- title: Dash AG Grid with pagination
+ - components:
+ - figure:
+ _target_: dash_ag_grid
+ data_frame: gapminder
+ dashGridOptions:
+ pagination: true
+ type: ag_grid
+ title: Dash AG Grid with pagination
```
- === "Result"
- [![AGGrid]][AGGrid]
- [AGGrid]: ../../assets/user_guides/table/aggrid-pagination.png
+ === "Result"
+ [![AGGrid]][aggrid]
### Formatting columns
#### Numbers
-One of the most common tasks when working with tables is to format the columns so that displayed numbers are more readable.
-To do this, you can use the native functionality of [value formatters](https://dash.plotly.com/dash-ag-grid/value-formatters)
-or the Vizro pre-defined [custom cell data types](https://dash.plotly.com/dash-ag-grid/cell-data-types#providing-custom-cell-data-types) as shown below.
+One of the most common tasks when working with tables is to format the columns so that displayed numbers are more readable. To do this, you can use the native functionality of [value formatters](https://dash.plotly.com/dash-ag-grid/value-formatters) or the Vizro pre-defined [custom cell data types](https://dash.plotly.com/dash-ag-grid/cell-data-types#providing-custom-cell-data-types) as shown below.
The available custom cell types for Vizro are `dollar`, `euro`, `percent` and `numeric`.
-To use these, define your desired `` alongside the chosen `cellDataType` in
-the `columnDefs` argument of your `dash_ag_grid` function:
+To use these, define your desired `` alongside the chosen `cellDataType` in the `columnDefs` argument of your `dash_ag_grid` function:
```py
columnDefs = [{"field": "", "cellDataType": "euro"}]
@@ -138,7 +120,6 @@ columnDefs = [{"field": "", "cellDataType": "euro"}]
In the example below we select and format some columns of the gapminder data.
!!! example "AG Grid with formatted columns"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -168,6 +149,7 @@ In the example below we select and format some columns of the gapminder data.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -190,33 +172,23 @@ In the example below we select and format some columns of the gapminder data.
type: ag_grid
title: Example of AG Grid with formatted columns
```
- === "Result"
- [![AGGrid2]][AGGrid2]
- [AGGrid2]: ../../assets/user_guides/table/formatted_aggrid.png
+ === "Result"
+ [![AGGrid2]][aggrid2]
#### Dates
-For the [`AgGrid`][vizro.models.AgGrid] model to sort and filter dates correctly, the date must either be of
-string format `yyyy-mm-dd` (see [Dash AG Grid docs](https://dash.plotly.com/dash-ag-grid/date-filters#example:-date-filter))
-or a pandas datetime object. Any pandas datetime column will be transformed into the `yyyy-mm-dd` format automatically.
+For the [`AgGrid`][vizro.models.AgGrid] model to sort and filter dates correctly, the date must either be of string format `yyyy-mm-dd` (see [Dash AG Grid docs](https://dash.plotly.com/dash-ag-grid/date-filters#example:-date-filter)) or a pandas datetime object. Any pandas datetime column will be transformed into the `yyyy-mm-dd` format automatically.
#### Objects and strings
-No specific formatting is available for custom objects and strings, however you can make use of [Value Formatters](https://dash.plotly.com/dash-ag-grid/value-formatters)
-to format displayed strings automatically.
-
+No specific formatting is available for custom objects and strings, however you can make use of [Value Formatters](https://dash.plotly.com/dash-ag-grid/value-formatters) to format displayed strings automatically.
### Styling and changing the AG Grid
-As mentioned above, all [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments. Below you can find
-an example of a styled AG Grid where some conditional formatting is applied, and where the columns are editable, but
-not filterable or resizable. There are more ways to alter the grid beyond this showcase. AG Grid, like any other Vizro
-component, can be customized using custom CSS. You can find information in
-the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-selected-components).
+As mentioned above, all [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments. Below you can find an example of a styled AG Grid where some conditional formatting is applied, and where the columns are editable, but not filterable or resizable. There are more ways to alter the grid beyond this showcase. AG Grid, like any other Vizro component, can be customized using custom CSS. You can find information in the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-selected-components).
!!! example "Styled and modified Dash AG Grid"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -284,6 +256,7 @@ the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-select
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -299,28 +272,28 @@ the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-select
- field: year
- field: lifeExp
valueFormatter:
- function: "d3.format('.1f')(params.value)"
+ function: d3.format('.1f')(params.value)
- field: gdpPercap
valueFormatter:
- function: "d3.format('$,.1f')(params.value)"
+ function: d3.format('$,.1f')(params.value)
cellStyle:
styleConditions:
- condition: params.value < 1045
style:
- backgroundColor: "#ff9222"
+ backgroundColor: '#ff9222'
- condition: params.value >= 1045 && params.value <= 4095
style:
- backgroundColor: "#de9e75"
+ backgroundColor: '#de9e75'
- condition: params.value > 4095 && params.value <= 12695
style:
- backgroundColor: "#aaa9ba"
+ backgroundColor: '#aaa9ba'
- condition: params.value > 12695
style:
- backgroundColor: "#00b4ff"
+ backgroundColor: '#00b4ff'
- field: pop
type: rightAligned
valueFormatter:
- function: "d3.format(',.0f')(params.value)"
+ function: d3.format(',.0f')(params.value)
defaultColDef:
resizable: false
filter: false
@@ -329,10 +302,9 @@ the [guide to overwriting CSS properties](custom-css.md#overwrite-css-for-select
type: ag_grid
title: Example of a Dash AG Grid
```
- === "Result"
- [![AGGrid3]][AGGrid3]
- [AGGrid3]: ../../assets/user_guides/table/styled_aggrid.png
+ === "Result"
+ [![AGGrid3]][aggrid3]
If the available arguments are not sufficient, there is always the option to [create a custom AG Grid callable](custom-tables.md).
@@ -348,19 +320,14 @@ The Vizro [`Table`][vizro.models.Table] model is based on the [Dash DataTable](h
To add a [`Table`][vizro.models.Table] to your page, do the following:
-1. Insert the [`Table`][vizro.models.Table] model into the `components` argument of the
-[`Page`][vizro.models.Page] model.
-2. Enter the `dash_data_table` function under the `figure` argument (imported via `from vizro.tables import dash_data_table`).
-
+1. Insert the [`Table`][vizro.models.Table] model into the `components` argument of the [`Page`][vizro.models.Page] model.
+1. Enter the `dash_data_table` function under the `figure` argument (imported via `from vizro.tables import dash_data_table`).
-The Vizro version of this table differs in one way from the original table: it requires the user to pass a pandas DataFrame as the source of data.
-As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`.
+The Vizro version of this table differs in one way from the original table: it requires the user to pass a pandas DataFrame as the source of data. As explained in [our guide to using data in Vizro](data.md), this must be entered under the argument `data_frame`.
-All other [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Note that we are
-setting some defaults for some arguments to help with styling.
+All other [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Note that we are setting some defaults for some arguments to help with styling.
!!! example "Dash DataTable"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -380,31 +347,29 @@ setting some defaults for some arguments to help with styling.
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: dash_data_table
- data_frame: gapminder_2007
- title: Dash DataTable
- type: table
- title: Example of a Dash DataTable
+ - components:
+ - figure:
+ _target_: dash_data_table
+ data_frame: gapminder_2007
+ title: Dash DataTable
+ type: table
+ title: Example of a Dash DataTable
```
- === "Result"
- [![Table]][Table]
- [Table]: ../../assets/user_guides/table/table.png
+ === "Result"
+ [![Table]][table]
### Styling and changing the Dash DataTable
-As mentioned above, all [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Below you can find
-an example of a styled table where some conditional formatting is applied. There are many more ways to alter the table beyond this showcase.
+As mentioned above, all [parameters of the Dash DataTable](https://dash.plotly.com/datatable/reference) can be entered as keyword arguments. Below you can find an example of a styled table where some conditional formatting is applied. There are many more ways to alter the table beyond this showcase.
!!! example "Styled Dash DataTable"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -467,6 +432,7 @@ an example of a styled table where some conditional formatting is applied. There
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -504,12 +470,12 @@ an example of a styled table where some conditional formatting is applied. There
backgroundColor: dodgerblue
color: white
- if:
- filter_query: "{lifeExp} < 55"
+ filter_query: '{lifeExp} < 55'
column_id: lifeExp
- backgroundColor: "#85144b"
+ backgroundColor: '#85144b'
color: white
- if:
- filter_query: "{gdpPercap} > 10000"
+ filter_query: '{gdpPercap} > 10000'
column_id: gdpPercap
backgroundColor: green
color: white
@@ -524,26 +490,20 @@ an example of a styled table where some conditional formatting is applied. There
title: Dash DataTable
```
- === "Result"
- [![Table2]][Table2]
- [Table2]: ../../assets/user_guides/table/styled_table.png
+ === "Result"
+ [![Table2]][table2]
If the available arguments are not sufficient, there is always the option to create a [custom Dash DataTable](custom-tables.md).
-
## Add title, header, and footer
-The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] models accept a `title`, `header` and
-`footer` argument. This is useful for providing context to the data being displayed, or for adding a description of
-the data.
+The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] models accept a `title`, `header` and `footer` argument. This is useful for providing context to the data being displayed, or for adding a description of the data.
- **title**: Displayed as an [H3 header](https://dash.plotly.com/dash-html-components/h3), useful for summarizing the main topic or insight of the component.
- **header**: Accepts markdown text, ideal for extra descriptions, subtitles, or detailed data insights.
- **footer**: Accepts markdown text, commonly used for citing data sources, providing information on the last update, or adding disclaimers.
-
-
### Formatted AgGrid
!!! example "Formatted AgGrid"
@@ -571,30 +531,29 @@ the data.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: dash_ag_grid
- data_frame: gapminder_2007
- dashGridOptions:
- pagination: true
- title: Gapminder Data Insights
- header: |
- #### An Interactive Exploration of Global Health, Wealth, and Population
- footer: |
- SOURCE: **Plotly gapminder data set, 2024**
- type: ag_grid
- title: Formatted AgGrid
+ - components:
+ - figure:
+ _target_: dash_ag_grid
+ data_frame: gapminder_2007
+ dashGridOptions:
+ pagination: true
+ title: Gapminder Data Insights
+ header: |
+ #### An Interactive Exploration of Global Health, Wealth, and Population
+ footer: |
+ SOURCE: **Plotly gapminder data set, 2024**
+ type: ag_grid
+ title: Formatted AgGrid
```
- === "Result"
- [![FormattedGrid]][FormattedGrid]
-
- [FormattedGrid]: ../../assets/user_guides/components/formatted_aggrid.png
+ === "Result"
+ [![FormattedGrid]][formattedgrid]
### Formatted DataTable
@@ -623,24 +582,32 @@ the data.
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: dash_data_table
- data_frame: gapminder_2007
- title: Gapminder Data Insights
- header: |
- #### An Interactive Exploration of Global Health, Wealth, and Population
- footer: |
- SOURCE: **Plotly gapminder data set, 2024**
- type: table
- title: Formatted DataTable
+ - components:
+ - figure:
+ _target_: dash_data_table
+ data_frame: gapminder_2007
+ title: Gapminder Data Insights
+ header: |
+ #### An Interactive Exploration of Global Health, Wealth, and Population
+ footer: |
+ SOURCE: **Plotly gapminder data set, 2024**
+ type: table
+ title: Formatted DataTable
```
- === "Result"
- [![FormattedTable]][FormattedTable]
- [FormattedTable]: ../../assets/user_guides/components/formatted_table.png
+ === "Result"
+ [![FormattedTable]][formattedtable]
+
+[aggrid]: ../../assets/user_guides/table/aggrid.png
+[aggrid2]: ../../assets/user_guides/table/formatted_aggrid.png
+[aggrid3]: ../../assets/user_guides/table/styled_aggrid.png
+[formattedgrid]: ../../assets/user_guides/components/formatted_aggrid.png
+[formattedtable]: ../../assets/user_guides/components/formatted_table.png
+[table]: ../../assets/user_guides/table/table.png
+[table2]: ../../assets/user_guides/table/styled_table.png
diff --git a/vizro-core/docs/pages/user-guides/tabs.md b/vizro-core/docs/pages/user-guides/tabs.md
index 09154177e..1811d0cac 100755
--- a/vizro-core/docs/pages/user-guides/tabs.md
+++ b/vizro-core/docs/pages/user-guides/tabs.md
@@ -1,8 +1,6 @@
# How to use tabs
-[`Tabs`][vizro.models.Tabs] organize and separate groups of related content in a dashboard, letting users switch between different sections or views.
-They are essentially a way of putting multiple [`Containers`][vizro.models.Container] in the same screen space, and letting the user switch between them.
-`Containers` enable the grouping of page components into sections and subsections. See our [user guide on `Containers`](container.md) for more information.
+[`Tabs`][vizro.models.Tabs] organize and separate groups of related content in a dashboard, letting users switch between different sections or views. They are essentially a way of putting multiple [`Containers`][vizro.models.Container] in the same screen space, and letting the user switch between them. `Containers` enable the grouping of page components into sections and subsections. See our [user guide on `Containers`](container.md) for more information.
{ width="400"}
@@ -16,14 +14,12 @@ This guide shows you how to use tabs to organize your `Containers` into subsecti
By using [`Tabs`][vizro.models.Tabs], the following applies:
- [`Filters`][vizro.models.Filter] affect all components on all tabs (opened and closed) of the page if not specified otherwise inside `Filter.targets`
-- The `title` of the [`Container`][vizro.models.Container] inserted into `Tabs.tabs` will be displayed as a tab label, and the title will be removed from the `Container`
-
+- The `title` of the [`Container`][vizro.models.Container] inserted into `Tabs.tabs` will be displayed as a tab label, and the title will be removed from the `Container`
To add [`Tabs`][vizro.models.Tabs] to your page, do the following:
1. Insert the [`Tabs`][vizro.models.Tabs] into the `components` argument of the [`Page`][vizro.models.Page]
-2. Insert your [`Containers`][vizro.models.Container] into the `tabs` argument of the [`Tabs`][vizro.models.Tabs]
-
+1. Insert your [`Containers`][vizro.models.Container] into the `tabs` argument of the [`Tabs`][vizro.models.Tabs]
!!! example "Tabs"
=== "app.py"
@@ -88,52 +84,53 @@ To add [`Tabs`][vizro.models.Tabs] to your page, do the following:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See from_yaml example
pages:
- - components:
- - tabs:
- - title: Tab I
- type: container
- components:
- - type: graph
- figure:
- _target_: bar
- data_frame: gapminder_2007
- title: Graph 1
- x: continent
- y: lifeExp
- color: continent
- - type: graph
- figure:
- _target_: box
- data_frame: gapminder_2007
- title: Graph 2
- x: continent
- y: lifeExp
- color: continent
- - title: Tab II
- type: container
- components:
- - type: graph
- figure:
- _target_: scatter
- data_frame: gapminder_2007
- title: Graph 3
- x: gdpPercap
- y: lifeExp
- size: pop
- color: continent
- type: tabs
+ components:
+ - type: tabs
+ tabs:
+ - title: Tab I
+ type: container
+ components:
+ - type: graph
+ figure:
+ _target_: bar
+ data_frame: gapminder_2007
+ title: Graph 1
+ x: continent
+ y: lifeExp
+ color: continent
+ - type: graph
+ figure:
+ _target_: box
+ data_frame: gapminder_2007
+ title: Graph 2
+ x: continent
+ y: lifeExp
+ color: continent
+ - title: Tab II
+ type: container
+ components:
+ - type: graph
+ figure:
+ _target_: scatter
+ data_frame: gapminder_2007
+ title: Graph 3
+ x: gdpPercap
+ y: lifeExp
+ size: pop
+ color: continent
controls:
- - type: filter
- column: continent
+ - type: filter
+ column: continent
title: Tabs
```
- === "Result"
- [![Tabs]][Tabs]
+ === "Result"
+ [![Tabs]][tabs]
- [Tabs]: ../../assets/user_guides/components/tabs.png
+[tabs]: ../../assets/user_guides/components/tabs.png
diff --git a/vizro-core/docs/pages/user-guides/themes.md b/vizro-core/docs/pages/user-guides/themes.md
index 6f78441d5..ac1d6fc7b 100644
--- a/vizro-core/docs/pages/user-guides/themes.md
+++ b/vizro-core/docs/pages/user-guides/themes.md
@@ -1,15 +1,13 @@
# How to use themes
-This guide shows you how to use themes. Themes are pre-designed collections of stylings that are applied to entire charts and dashboards.
-The themes provided by Vizro are infused with our design best practices that make charts and dashboards look visually consistent and professional.
+This guide shows you how to use themes. Themes are pre-designed collections of stylings that are applied to entire charts and dashboards. The themes provided by Vizro are infused with our design best practices that make charts and dashboards look visually consistent and professional.
## Themes in dashboards
-The [`Dashboard`][vizro.models.Dashboard] model accepts an optional `theme` argument, where you can choose between
-a `vizro_dark` and a `vizro_light` theme. If not specified then `theme` defaults to `vizro_dark`. The theme is applied to the entire dashboard and its charts/components when a user first loads your dashboard. Regardless of the theme applied on first load, users can always switch between light and dark themes via the toggle button in the upper-right corner of the dashboard.
+
+The [`Dashboard`][vizro.models.Dashboard] model accepts an optional `theme` argument, where you can choose between a `vizro_dark` and a `vizro_light` theme. If not specified then `theme` defaults to `vizro_dark`. The theme is applied to the entire dashboard and its charts/components when a user first loads your dashboard. Regardless of the theme applied on first load, users can always switch between light and dark themes via the toggle button in the upper-right corner of the dashboard.
!!! example "Change theme"
=== "app.py"
-
```{.python pycafe-link hl_lines="18"}
import vizro.models as vm
import vizro.plotly.express as px
@@ -32,47 +30,40 @@ a `vizro_dark` and a `vizro_light` theme. If not specified then `theme` defaults
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml hl_lines="12"
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: scatter_matrix
- color: species
- data_frame: iris
- dimensions: ["sepal_length", "sepal_width", "petal_length", "petal_width"]
- type: graph
- title: Changing themes
+ - components:
+ - figure:
+ _target_: scatter_matrix
+ color: species
+ data_frame: iris
+ dimensions: [sepal_length, sepal_width, petal_length, petal_width]
+ type: graph
+ title: Changing themes
theme: vizro_light
```
+
=== "Result - vizro_light"
- [![Light]][Light]
+ [![Light]][light]
- [Light]: ../../assets/user_guides/themes/light.png
=== "Result - vizro_dark"
- [![Dark]][Dark]
-
- [Dark]: ../../assets/user_guides/themes/dark.png
-
+ [![Dark]][dark]
## Themes in plotly charts
You can also use our templates for plotly charts outside the dashboard. This is useful in a few contexts:
-* Creation of standalone charts to be used independently of a Vizro dashboard.
-* Rapid development of charts for eventual use in a Vizro dashboard, for example in a Jupyter Notebook.
+- Creation of standalone charts to be used independently of a Vizro dashboard.
+- Rapid development of charts for eventual use in a Vizro dashboard, for example in a Jupyter Notebook.
!!! note
+ Using `import vizro.plotly.express as px` is equal to using `import plotly.express as px`, but with the added benefit of being able to integrate the resulting chart code into a Vizro dashboard. Vizro offers a minimal layer on top of Plotly's existing charting library, allowing you to seamlessly use all the existing charts and functionalities provided by plotly.express without any modifications.
- Using `import vizro.plotly.express as px` is equivalent to using `import plotly.express as px`,
- but with the added benefit of being able to integrate the resulting chart code into a Vizro dashboard.
- Vizro offers a minimal layer on top of Plotly's existing charting library, allowing you to seamlessly use all the
- existing charts and functionalities provided by plotly.express without any modifications.
-
-Our `vizro_dark` and `vizro_light` themes are automatically registered to `plotly.io.templates` when importing Vizro.
-Consult the plotly documentation for [more details on how templates work in plotly](https://plotly.com/python/templates/#theming-and-templates).
+Our `vizro_dark` and `vizro_light` themes are automatically registered to `plotly.io.templates` when importing Vizro. Consult the plotly documentation for [more details on how templates work in plotly](https://plotly.com/python/templates/#theming-and-templates).
By default, plots imported from `vizro.plotly.express` have the `vizro_dark` theme applied. This can be altered either globally or for individual plots.
@@ -87,14 +78,20 @@ pio.templates.default = "vizro_light"
```
### Set themes for selected charts
+
To change the template for a selected chart only, use the `template` parameter and run:
```python
import vizro.plotly.express as px
df = px.data.iris()
-px.scatter_matrix(df,
- dimensions=["sepal_length", "sepal_width", "petal_length", "petal_width"],
- color="species",
- template="vizro_light")
+px.scatter_matrix(
+ df,
+ dimensions=["sepal_length", "sepal_width", "petal_length", "petal_width"],
+ color="species",
+ template="vizro_light",
+)
```
+
+[dark]: ../../assets/user_guides/themes/dark.png
+[light]: ../../assets/user_guides/themes/light.png
diff --git a/vizro-core/docs/pages/user-guides/visual-formatting.md b/vizro-core/docs/pages/user-guides/visual-formatting.md
index 7b384f3e9..56d1d2d52 100644
--- a/vizro-core/docs/pages/user-guides/visual-formatting.md
+++ b/vizro-core/docs/pages/user-guides/visual-formatting.md
@@ -1,17 +1,13 @@
# How to customize the style of Vizro dashboards
-Vizro has a default styling to help users with no design experience get started.
-There are several options if you want to customize the style:
+Vizro has a default styling to help users with no design experience get started. There are several options if you want to customize the style:
-* **[Configure the `Layout`](layouts.md)**: Customize the arrangement of your components inside your Vizro dashboard.
+- **[Configure the `Layout`](layouts.md)**: Customize the arrangement of your components inside your Vizro dashboard.
-* **[Apply a theme](themes.md)**: Choose between a dark or light theme.
+- **[Apply a theme](themes.md)**: Choose between a dark or light theme.
-* **[Manage assets](assets.md)**: Enhance your dashboard by adding images, scripts, and stylesheets to your assets folder.
+- **[Manage assets](assets.md)**: Enhance your dashboard by adding images, scripts, and stylesheets to your assets folder.
-* **[Customize CSS](custom-css.md)**: Incorporate custom CSS to deviate from the default styling and create a
-unique appearance for your Vizro dashboard.
+- **[Customize CSS](custom-css.md)**: Incorporate custom CSS to deviate from the default styling and create a unique appearance for your Vizro dashboard.
-* **[Customize your `component`](components.md)**: Change the appearance of components like the [Graph](graph.md), the
-[Table](table.md) and the [AgGrid](table.md), by passing extra arguments. Refer to the relevant user guide for
-more details.
+- **[Customize your `component`](components.md)**: Change the appearance of components like the [Graph](graph.md), the [Table](table.md) and the [AgGrid](table.md), by passing extra arguments. Refer to the relevant user guide for more details.
diff --git a/vizro-core/examples/README.md b/vizro-core/examples/README.md
index 72146bfb7..53cf932b7 100644
--- a/vizro-core/examples/README.md
+++ b/vizro-core/examples/README.md
@@ -4,8 +4,7 @@ Please note that this folder contains only example dashboards that are still **i
### Vizro examples gallery
-To view a comprehensive list of available demos, please visit our [examples gallery](http://vizro.mckinsey.com/).
-There, you can explore a wide range of dashboards and applications created with Vizro.
+To view a comprehensive list of available demos, please visit our [examples gallery](http://vizro.mckinsey.com/). There, you can explore a wide range of dashboards and applications created with Vizro.
diff --git a/vizro-core/examples/visual-vocabulary/README.md b/vizro-core/examples/visual-vocabulary/README.md
index 3b298520e..e59b3103c 100644
--- a/vizro-core/examples/visual-vocabulary/README.md
+++ b/vizro-core/examples/visual-vocabulary/README.md
@@ -2,14 +2,11 @@
### Welcome to our visual vocabulary dashboard! 🎨
-This dashboard serves as a comprehensive guide for selecting and creating various types of charts. It helps you decide
-when to use each chart type, and offers sample Python code using [Plotly](https://plotly.com/python/), and
-instructions for embedding these charts into a [Vizro](https://github.com/mckinsey/vizro) dashboard.
+This dashboard serves as a comprehensive guide for selecting and creating various types of charts. It helps you decide when to use each chart type, and offers sample Python code using [Plotly](https://plotly.com/python/), and instructions for embedding these charts into a [Vizro](https://github.com/mckinsey/vizro) dashboard.
The charts in this dashboard are designed to make it easy for anyone to create beautiful and sophisticated visuals.
-Our goal is to help you understand best practices in data visualization, ensure your charts effectively communicate
-your message, and streamline the creation of high-quality, interactive visualizations.
+Our goal is to help you understand best practices in data visualization, ensure your charts effectively communicate your message, and streamline the creation of high-quality, interactive visualizations.
Created by:
@@ -19,12 +16,9 @@ Created by:
Inspired by:
-- [The FT Visual Vocabulary](https://github.com/Financial-Times/chart-doctor/blob/main/visual-vocabulary/README.md):
- [Alan Smith](https://github.com/alansmithy), [Chris Campbell](https://github.com/digitalcampbell), Ian Bott,
- Liz Faunce, Graham Parrish, Billy Ehrenberg, Paul McCallum, [Martin Stabe](https://github.com/martinstabe).
+- [The FT Visual Vocabulary](https://github.com/Financial-Times/chart-doctor/blob/main/visual-vocabulary/README.md): [Alan Smith](https://github.com/alansmithy), [Chris Campbell](https://github.com/digitalcampbell), Ian Bott, Liz Faunce, Graham Parrish, Billy Ehrenberg, Paul McCallum, [Martin Stabe](https://github.com/martinstabe).
-- [The Graphic Continuum](https://www.informationisbeautifulawards.com/showcase/611-the-graphic-continuum):
- Jon Swabish and Severino Ribecca
+- [The Graphic Continuum](https://www.informationisbeautifulawards.com/showcase/611-the-graphic-continuum): Jon Swabish and Severino Ribecca
Credits and sources:
@@ -102,13 +96,12 @@ The dashboard is still in development. Below is an overview of the chart types f
Contributions are welcome! To contribute a chart, follow the steps below:
1. Check that a `svg` file named after the chart type is contained in the [assets](https://github.com/mckinsey/vizro/tree/main/vizro-core/examples/visual-vocabulary/assets/images/charts) folder. If not, [raise an issue](https://github.com/mckinsey/vizro/issues) in the repository.
-2. Add a `.py` file containing a code example of the chart type in the `pages/examples` folder, for instance, `area.py`. Take a look at existing examples.
-3. Create a new page for the chart type and add it to the relevant category `.py` file such as `correlation.py`,
- `deviation.py`, `distribution.py`, etc. Ensure you add the page to the list of `pages` at the end of the `.py` file.
-4. Remove the `IncompletePage(..)` entry for that chart type in `chart_groups.py`.
-5. Update this `README.md` with the new chart type, its status, category, and API links.
+1. Add a `.py` file containing a code example of the chart type in the `pages/examples` folder, for instance, `area.py`. Take a look at existing examples.
+1. Create a new page for the chart type and add it to the relevant category `.py` file such as `correlation.py`, `deviation.py`, `distribution.py`, etc. Ensure you add the page to the list of `pages` at the end of the `.py` file.
+1. Remove the `IncompletePage(..)` entry for that chart type in `chart_groups.py`.
+1. Update this `README.md` with the new chart type, its status, category, and API links.
## How to run the example locally
1. Run the example with the command `hatch run example visual-vocabulary`.
-2. You should now be able to access the app locally via http://127.0.0.1:8051/.
+1. You should now be able to access the app locally via http://127.0.0.1:8051/.
Run and edit this code in PyCafe
=== "styling.css"
```css
.multiple-cards-container {
- display: flex;
- flex-wrap: wrap;
- gap: 12px;
+ display: flex;
+ flex-wrap: wrap;
+ gap: 12px;
}
.figure-container {
- height: unset;
- width: unset;
+ height: unset;
+ width: unset;
}
.figure-container .card {
- height: 210px;
- width: 240px;
+ height: 210px;
+ width: 240px;
}
```
- === "app.yaml"
- ```yaml
- # Custom figures are currently only possible via Python configuration
- ```
- === "Result"
- [![CustomFigure]][CustomFigure]
- [CustomFigure]: ../../assets/user_guides/figure/custom_multiple_cards.png
+ === "app.yaml"
+ Custom figures are currently only possible via Python configuration.
+ === "Result"
+ [![CustomFigure]][customfigure]
+
+[customfigure]: ../../assets/user_guides/figure/custom_multiple_cards.png
+[customhtml]: ../../assets/user_guides/figure/custom_html.png
+[customkpi]: ../../assets/user_guides/figure/custom_kpi.png
diff --git a/vizro-core/docs/pages/user-guides/custom-tables.md b/vizro-core/docs/pages/user-guides/custom-tables.md
index e990cfbb0..42748820b 100644
--- a/vizro-core/docs/pages/user-guides/custom-tables.md
+++ b/vizro-core/docs/pages/user-guides/custom-tables.md
@@ -1,21 +1,18 @@
# How to create custom Dash AG Grids and Dash DataTables
-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.
+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.
-The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] model accept the `figure` argument, where you can enter
-_any_ [`dash_ag_grid`][vizro.tables.dash_ag_grid] or [`dash_data_table`][vizro.tables.dash_data_table] chart as explained in the [user guide on tables](table.md).
+The [`Table`][vizro.models.Table] and the [`AgGrid`][vizro.models.AgGrid] model accept the `figure` argument, where you can enter _any_ [`dash_ag_grid`][vizro.tables.dash_ag_grid] or [`dash_data_table`][vizro.tables.dash_data_table] chart as explained in the [user guide on tables](table.md).
One reason could be that you want to create a table/grid that requires computations that can be controlled by parameters (see the example below).
### Steps to create a custom table
1. Define a function that returns a `dash_ag_grid.AgGrid` or `dash_table.DataTable` object.
-2. Decorate it with `@capture("ag_grid")` or `@capture("table")`.
-3. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
-4. The table should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments
-will not react to dashboard controls such as [`Filter`](filters.md).
-5. Pass your function to the `figure` argument of the [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid] model.
+1. Decorate it with `@capture("ag_grid")` or `@capture("table")`.
+1. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
+1. The table should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments will not react to dashboard controls such as [`Filter`](filters.md).
+1. Pass your function to the `figure` argument of the [`Table`][vizro.models.Table] or [`AgGrid`][vizro.models.AgGrid] model.
The following examples show a possible version of a custom table. In this case the argument `chosen_columns` was added, which you can control with a parameter:
@@ -70,14 +67,12 @@ The following examples show a possible version of a custom table. In this case t
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
- ```yaml
- # Custom tables are currently only possible via Python configuration
- ```
- === "Result"
- [![Table3]][Table3]
+ Custom tables are currently only possible via Python configuration.
- [Table3]: ../../assets/user_guides/table/custom_table.png
+ === "Result"
+ [![Table3]][table3]
??? example "Custom Dash AgGrid"
=== "app.py"
@@ -136,11 +131,12 @@ The following examples show a possible version of a custom table. In this case t
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
- ```yaml
- # Custom Ag Grids are currently only possible via Python configuration
- ```
+ Custom Ag Grids are currently only possible via Python configuration.
+
=== "Result"
- [![GridCustom]][GridCustom]
+ [![GridCustom]][gridcustom]
- [GridCustom]: ../../assets/user_guides/table/custom_grid.png
+[gridcustom]: ../../assets/user_guides/table/custom_grid.png
+[table3]: ../../assets/user_guides/table/custom_table.png
diff --git a/vizro-core/docs/pages/user-guides/dashboard.md b/vizro-core/docs/pages/user-guides/dashboard.md
index 0b37e03fa..244f65256 100644
--- a/vizro-core/docs/pages/user-guides/dashboard.md
+++ b/vizro-core/docs/pages/user-guides/dashboard.md
@@ -1,16 +1,15 @@
# How to create a dashboard
-This guide shows you how to configure and call a [`Dashboard`][vizro.models.Dashboard] using either
-pydantic models, Python dictionaries, YAML, or JSON.
+
+This guide shows you how to configure and call a [`Dashboard`][vizro.models.Dashboard] using either pydantic models, Python dictionaries, YAML, or JSON.
To create a dashboard:
1. Choose one of the possible configuration syntaxes
-2. Create your `pages`, see our [guide on Pages](pages.md)
-3. (optional) Choose a `theme`, see our [guide on Themes](themes.md)
-4. (optional) Customize your `navigation`, see our [guide on Navigation](navigation.md)
-5. (optional) Set a `title` for your dashboard
-6. Add your `dashboard` to the `build` call of Vizro
-
+1. Create your `pages`, see our [guide on Pages](pages.md)
+1. (optional) Choose a `theme`, see our [guide on Themes](themes.md)
+1. (optional) Customize your `navigation`, see our [guide on Navigation](navigation.md)
+1. (optional) Set a `title` for your dashboard
+1. Add your `dashboard` to the `build` call of Vizro
## Use dashboard configuration options
@@ -37,6 +36,7 @@ To create a dashboard:
Vizro().build(dashboard).run()
```
+
=== "app.py - Python dict"
```py
import vizro.plotly.express as px
@@ -77,6 +77,7 @@ To create a dashboard:
Vizro().build(dashboard).run()
```
+
=== "dashboard.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -101,50 +102,49 @@ To create a dashboard:
type: filter
title: My first dashboard
```
+
=== "dashboard.json"
```json
{
- "pages": [
+ "pages": [
+ {
+ "components": [
+ {
+ "figure": {
+ "_target_": "scatter",
+ "color": "species",
+ "data_frame": "iris",
+ "x": "sepal_length",
+ "y": "petal_width"
+ },
+ "type": "graph"
+ },
{
- "components": [
- {
- "figure": {
- "_target_": "scatter",
- "color": "species",
- "data_frame": "iris",
- "x": "sepal_length",
- "y": "petal_width"
- },
- "type": "graph"
- },
- {
- "figure": {
- "_target_": "histogram",
- "color": "species",
- "data_frame": "iris",
- "x": "sepal_width",
- },
- "type": "graph"
- }
- ],
- "controls": [
- {
- "column": "species",
- "type": "filter"
- }
- ],
- "title": "My first dashboard"
+ "figure": {
+ "_target_": "histogram",
+ "color": "species",
+ "data_frame": "iris",
+ "x": "sepal_width"
+ },
+ "type": "graph"
}
- ]
+ ],
+ "controls": [
+ {
+ "column": "species",
+ "type": "filter"
+ }
+ ],
+ "title": "My first dashboard"
+ }
+ ]
}
```
- === "Result"
- [![Dashboard]][Dashboard]
- [Dashboard]: ../../assets/user_guides/dashboard/dashboard.png
+ === "Result"
+ [![Dashboard]][dashboard]
!!! note "Extra `.py` files for `yaml` and `json` required"
-
Note that in the `yaml` and `json` example an extra `.py` is required to register the data and parse the yaml/json configuration.
=== "app.py for yaml"
@@ -164,6 +164,7 @@ To create a dashboard:
Vizro().build(dashboard).run()
```
+
=== "app.py for json"
```py
import json
@@ -187,7 +188,6 @@ After running the dashboard, you can access the dashboard via `localhost:8050`.
If supplied, the `title` of the [`Dashboard`][vizro.models.Dashboard] displays a heading at the top of every page.
-
## Add a dashboard logo
Vizro will [automatically incorporate the dashboard logo](assets.md/#add-a-logo-image) in the top-left corner of each page if an image named `logo. | | `layout=vm.Layout(grid=[[0]])` |
-| | | `layout=vm.Layout(grid=[[0],[1]])` |
-| | | `layout=vm.Layout(grid=[[0,1]])` |
-| | | `layout=vm.Layout(grid=[[0],[1],[2]])` or `layout=None` | -|
| | `layout=vm.Layout(grid=[[0,1],[0,2]])` |
-| | | `layout=vm.Layout(grid=[[0,0],[1,2]])` |
-| | | `layout=vm.Layout(grid=[[0,1],[2,2]])` |
-| | | `layout=vm.Layout(grid=[[0,1],[0,2],[0,3]])` |
-| | | `layout=vm.Layout(grid=[[0,1],[2,3]])` |
-| | | `layout=vm.Layout(grid=[[0,3],[1,3],[2,3]])` |
-| | | `layout=vm.Layout(grid=[[0,0,0],[1,2,3]])` |
-| | | `layout=vm.Layout(grid=[[0,1,2],[3,3,3]])` |
+| Layout needed | Grid | Code |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| | | `layout=vm.Layout(grid=[[0]])` |
+| | | `layout=vm.Layout(grid=[[0],[1]])` |
+| | | `layout=vm.Layout(grid=[[0,1]])` |
+| | | `layout=vm.Layout(grid=[[0],[1],[2]])` or `layout=None` | +|
| | `layout=vm.Layout(grid=[[0,1],[0,2]])` |
+| | | `layout=vm.Layout(grid=[[0,0],[1,2]])` |
+| | | `layout=vm.Layout(grid=[[0,1],[2,2]])` |
+| | | `layout=vm.Layout(grid=[[0,1],[0,2],[0,3]])` |
+| | | `layout=vm.Layout(grid=[[0,1],[2,3]])` |
+| | | `layout=vm.Layout(grid=[[0,3],[1,3],[2,3]])` |
+| | | `layout=vm.Layout(grid=[[0,0,0],[1,2,3]])` |
+| | | `layout=vm.Layout(grid=[[0,1,2],[3,3,3]])` |
## Add empty sections to the grid
+
One approach to organize the dashboard's layout involves integrating empty sections by specifying `-1` within the grid layout.
```python title="Example"
-grid = [[0, 1, -1],
- [0, 2, -1]]
+grid = [[0, 1, -1], [0, 2, -1]]
```
!!! example "Adding Empty Spaces"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -316,38 +308,38 @@ grid = [[0, 1, -1],
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- - text: |
- # Component 2
- type: card
- layout:
- grid: [[0, 1, -1], [0, 2, -1]]
- title: Adding empty spaces
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ layout:
+ grid: [[0, 1, -1], [0, 2, -1]]
+ title: Adding empty spaces
```
- === "Result"
- [![GridEmpty]][GridEmpty]
- [GridEmpty]: ../../assets/user_guides/layout/layout_empty_spaces.png
+ === "Result"
+ [![GridEmpty]][gridempty]
## Control the scroll behavior
+
By default, the grid fits all charts/components on the screen. This can lead to distortions such that the chart/component looks squashed. To control the scroll behavior, you can specify the following:
- `row_min_height`: Sets a chart/component's minimum height. Defaults to 0px.
- `col_min_width`: Sets a chart/component's minimum width. Defaults to 0px.
!!! example "Activate Scrolling"
-
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
@@ -371,59 +363,63 @@ By default, the grid fits all charts/components on the screen. This can lead to
dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - text: |
- # Component 0
- type: card
- - text: |
- # Component 1
- type: card
- - text: |
- # Component 2
- type: card
- - text: |
- # Component 2
- type: card
- - text: |
- # Component 4
- type: card
- - text: |
- # Component 5
- type: card
- - text: |
- # Component 6
- type: card
- - text: |
- # Component 7
- type: card
- layout:
- grid: [[0], [1], [2], [3], [4], [5], [6], [7]]
- row_min_height: 240px
- title: Activate scrolling
+ - components:
+ - text: |
+ # Component 0
+ type: card
+ - text: |
+ # Component 1
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ - text: |
+ # Component 2
+ type: card
+ - text: |
+ # Component 4
+ type: card
+ - text: |
+ # Component 5
+ type: card
+ - text: |
+ # Component 6
+ type: card
+ - text: |
+ # Component 7
+ type: card
+ layout:
+ grid: [[0], [1], [2], [3], [4], [5], [6], [7]]
+ row_min_height: 240px
+ title: Activate scrolling
```
- === "Result"
- [![GridScroll]][GridScroll]
-
- [GridScroll]: ../../assets/user_guides/layout/grid_scroll.png
+ === "Result"
+ [![GridScroll]][gridscroll]
## Further customization
-For further customization, such as changing the gap between row and column, refer to the
-documentation of the [`Layout`][vizro.models.Layout] model.
+
+For further customization, such as changing the gap between row and column, refer to the documentation of the [`Layout`][vizro.models.Layout] model.
## Alternative layout approaches
+
In general, any arbitrarily granular layout can already be achieved using [`Page.layout`](layouts.md) alone and is our recommended approach if you want to arrange components on a page with consistent row and/or column spacing.
!!! note "Alternative layout approaches: `Tabs` and `Containers`"
-
- [`Tabs`][vizro.models.Tabs] and [`Containers`][vizro.models.Container] provide an alternative approach to customize your page layout.
- For example, if you want to have more granular control and break the overall page grid into subgrids, see our [user guide on Containers](container.md).
+ [`Tabs`][vizro.models.Tabs] and [`Containers`][vizro.models.Container] offer an alternative approach to customize your page layout. For example, if you want to have more granular control and break the overall page grid into subgrids, see our [user guide on Containers](container.md).
If you want to display multiple containers on one page by putting them into the same screen space, and letting the user switch between them, see our [user guide on Tabs](tabs.md).
{ width="500" }
+
+[grid]: ../../assets/user_guides/layout/one_left_two_right.png
+[gridadv]: ../../assets/user_guides/layout/grid_advanced.png
+[gridempty]: ../../assets/user_guides/layout/layout_empty_spaces.png
+[gridscroll]: ../../assets/user_guides/layout/grid_scroll.png
+[layout]: ../../assets/user_guides/layout/two_left.png
diff --git a/vizro-core/docs/pages/user-guides/navigation.md b/vizro-core/docs/pages/user-guides/navigation.md
index 41c6bb9dc..75a661470 100644
--- a/vizro-core/docs/pages/user-guides/navigation.md
+++ b/vizro-core/docs/pages/user-guides/navigation.md
@@ -2,8 +2,7 @@
This guide shows you how to use and customize the navigation that appears on the left of your dashboard.
-The [`Dashboard`][vizro.models.Dashboard] model accepts a `navigation` argument, where you can enter a [`Navigation`][vizro.models.Navigation] model. This enables you to group pages together and customize how they appear in your navigation.
-The dashboard includes a collapsible side panel that users can minimize or expand by a button click. The collapse button, located in the top right corner of the side panel, is visible by default for user convenience.
+The [`Dashboard`][vizro.models.Dashboard] model accepts a `navigation` argument, where you can enter a [`Navigation`][vizro.models.Navigation] model. This enables you to group pages together and customize how they appear in your navigation. The dashboard includes a collapsible side panel that users can minimize or expand by a button click. The collapse button, located in the top right corner of the side panel, is visible by default for user convenience.
## Use the default navigation
@@ -56,8 +55,8 @@ By default, if the `navigation` argument is not specified, Vizro creates a navig
type: graph
title: My first page
- components:
- - text: My text here
- type: card
+ - text: My text here
+ type: card
title: My second page
- components:
- figure:
@@ -69,10 +68,9 @@ By default, if the `navigation` argument is not specified, Vizro creates a navig
type: graph
title: My third page
```
- === "Result"
- [![DefaultNavigation]][DefaultNavigation]
- [DefaultNavigation]: ../../assets/user_guides/navigation/default_navigation.png
+ === "Result"
+ [![DefaultNavigation]][defaultnavigation]
## Include a subset of pages
@@ -132,17 +130,15 @@ To include only some of your dashboard pages in your navigation then list them i
- My first page
- My second page
```
- === "Result"
- [![OnlySomePages]][OnlySomePages]
- [OnlySomePages]: ../../assets/user_guides/navigation/only_some_pages.png
+ === "Result"
+ [![OnlySomePages]][onlysomepages]
## Group pages
You can also group your pages together by specifying `pages` as a dictionary:
!!! example "Grouping pages"
-
=== "snippet.py"
```py
# page_1, page_2, page_3 defined as in default example
@@ -154,7 +150,6 @@ You can also group your pages together by specifying `pages` as a dictionary:
```
=== "app.py"
-
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -187,6 +182,7 @@ You can also group your pages together by specifying `pages` as a dictionary:
)
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
@@ -200,18 +196,15 @@ You can also group your pages together by specifying `pages` as a dictionary:
Group B:
- My third page
```
- === "Result"
- [![GroupedNavigation]][GroupedNavigation]
-
- [GroupedNavigation]: ../../assets/user_guides/navigation/grouped_navigation.png
+ === "Result"
+ [![GroupedNavigation]][groupednavigation]
## Use a navigation bar with icons
Another way to group together pages in the navigation is to use a [`NavBar`][vizro.models.NavBar] with icons. The simplest way to use this is to change the `nav_selector` specified in [`Navigation`][vizro.models.Navigation]:
!!! example "Using `NavBar`"
-
=== "snippet.py"
```py
# page_1, page_2, page_3 defined as in default example
@@ -223,8 +216,8 @@ Another way to group together pages in the navigation is to use a [`NavBar`][viz
)
Vizro().build(dashboard).run()
```
- === "app.py"
+ === "app.py"
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -276,14 +269,11 @@ Another way to group together pages in the navigation is to use a [`NavBar`][viz
nav_selector:
type: nav_bar
```
- === "Result"
- [![NavBar]][NavBar]
-
- [NavBar]: ../../assets/user_guides/navigation/nav_bar.png
+ === "Result"
+ [![NavBar]][navbar]
-Here, the first level of the navigation hierarchy ("Group A" and "Group B") is represented by an icon in a navigation bar, and the second level of the navigation (the pages) is represented by an accordion.
-By default, the set of icons used are the [`filter` icons from the Google Material icons library](https://fonts.google.com/icons?icon.query=filter). The icon label ("Group A" and "Group B") appears as a tooltip on hovering over the icon.
+Here, the first level of the navigation hierarchy ("Group A" and "Group B") is represented by an icon in a navigation bar, and the second level of the navigation (the pages) is represented by an accordion. By default, the set of icons used are the [`filter` icons from the Google Material icons library](https://fonts.google.com/icons?icon.query=filter). The icon label ("Group A" and "Group B") appears as a tooltip on hovering over the icon.
## Customize the navigation bar
@@ -314,7 +304,6 @@ The same configuration for [grouping pages](#group-pages) applies inside a `NavL
```
=== "app.py"
-
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -375,10 +364,9 @@ The same configuration for [grouping pages](#group-pages) applies inside a `NavL
Group B:
- My third page
```
- === "Result"
- [![AccordionInsideNavBar]][AccordionInsideNavBar]
- [AccordionInsideNavBar]: ../../assets/user_guides/navigation/accordion_inside_nav_bar.png
+ === "Result"
+ [![AccordionInsideNavBar]][accordioninsidenavbar]
You can alter the icons used by specifying the name of the icon in the [Google Material icons library](https://fonts.google.com/icons):
@@ -402,8 +390,8 @@ You can alter the icons used by specifying the name of the icon in the [Google M
),
)
```
- === "app.py"
+ === "app.py"
```{.python pycafe-link}
from vizro import Vizro
import vizro.plotly.express as px
@@ -468,7 +456,13 @@ You can alter the icons used by specifying the name of the icon in the [Google M
pages:
- My third page
```
- === "Result"
- [![CustomIcons]][CustomIcons]
- [CustomIcons]: ../../assets/user_guides/navigation/custom_icons.png
+ === "Result"
+ [![CustomIcons]][customicons]
+
+[accordioninsidenavbar]: ../../assets/user_guides/navigation/accordion_inside_nav_bar.png
+[customicons]: ../../assets/user_guides/navigation/custom_icons.png
+[defaultnavigation]: ../../assets/user_guides/navigation/default_navigation.png
+[groupednavigation]: ../../assets/user_guides/navigation/grouped_navigation.png
+[navbar]: ../../assets/user_guides/navigation/nav_bar.png
+[onlysomepages]: ../../assets/user_guides/navigation/only_some_pages.png
diff --git a/vizro-core/docs/pages/user-guides/pages.md b/vizro-core/docs/pages/user-guides/pages.md
index 7ae944e9b..71e01e9f9 100644
--- a/vizro-core/docs/pages/user-guides/pages.md
+++ b/vizro-core/docs/pages/user-guides/pages.md
@@ -1,7 +1,6 @@
# How to use pages
-This guide shows you how to add pages to your dashboard and customize the URL paths if needed.
-A [`Page`][vizro.models.Page] lets you place and arrange your dashboard content (for example, chart/components, tables, and text)
-and configure your dashboard interactions (such as filters and parameters).
+
+This guide shows you how to add pages to your dashboard and customize the URL paths if needed. A [`Page`][vizro.models.Page] lets you place and arrange your dashboard content (for example, chart/components, tables, and text) and configure your dashboard interactions (such as filters and parameters).
The [`Dashboard`][vizro.models.Dashboard] model accepts the `pages` argument, where you can insert your [`Page`][vizro.models.Page].
@@ -10,19 +9,19 @@ The [`Dashboard`][vizro.models.Dashboard] model accepts the `pages` argument, wh
A [`Page`][vizro.models.Page] is split up into four main containers:
1. The **navigation container** where you can customize your `navigation` (see [Dashboard](dashboard.md) and [Navigation](navigation.md) for more information). Note that the navigation container needs to be configured via the Dashboard.
-2. The **control container** where you can add your `controls` (see [Filters](filters.md) or [Parameters](parameters.md)) to interact with the dashboard
-3. The **page header** that contains the page title and the theme toggle switch button
-4. The **component container** where you can add your [components](components.md) to visualize your data
+1. The **control container** where you can add your `controls` (see [Filters](filters.md) or [Parameters](parameters.md)) to interact with the dashboard
+1. The **page header** that contains the page title and the theme toggle switch button
+1. The **component container** where you can add your [components](components.md) to visualize your data
To create and add a page to your dashboard, do the following steps:
1. Set a `title` for your [`Page`][vizro.models.Page]
-2. Configure your `components`, see our guide on the [various options](components.md)
-3. (optional) Configure your `controls` , see our guides on [Filters](filters.md) and [Parameters](parameters.md)
-4. (optional) Configure your `layout` , see our guide on [Layouts](layouts.md)
-5. (optional) Give a `description` of your `Page` to the app's [meta tags](https://metatags.io/)
+1. Configure your `components`, see our guide on the [various options](components.md)
+1. (optional) Configure your `controls` , see our guides on [Filters](filters.md) and [Parameters](parameters.md)
+1. (optional) Configure your `layout` , see our guide on [Layouts](layouts.md)
+1. (optional) Give a `description` of your `Page` to the app's [meta tags](https://metatags.io/)
!!! example "Page"
=== "app.py"
@@ -51,51 +50,47 @@ To create and add a page to your dashboard, do the following steps:
Vizro().build(dashboard).run()
```
+
=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- - components:
- - figure:
- _target_: sunburst
- path: ['continent', 'country']
- values: pop
- color: lifeExp
- data_frame: gapminder
- id: sunburst
- type: graph
- controls:
- - column: continent
- targets:
- - sunburst
- type: filter
- - selector:
- options: ['lifeExp', 'pop']
- title: Color
- type: radio_items
- targets:
- - sunburst.color
- type: parameter
- title: Page Title
- description: "Longer description of the page content"
+ - components:
+ - figure:
+ _target_: sunburst
+ path: [continent, country]
+ values: pop
+ color: lifeExp
+ data_frame: gapminder
+ id: sunburst
+ type: graph
+ controls:
+ - column: continent
+ targets: [sunburst]
+ type: filter
+ - selector:
+ options: [lifeExp, pop]
+ title: Color
+ type: radio_items
+ targets: [sunburst.color]
+ type: parameter
+ title: Page Title
+ description: Longer description of the page content
```
- === "Result"
- [![Page]][Page]
- [Page]: ../../assets/user_guides/pages/page_sunburst.png
+ === "Result"
+ [![Page]][page]
An accordion page selector is automatically added to your dashboard in the top-left of the control container for through the different pages. It will not be added if your dashboard consists of only one page.
You can additionally navigate through the different pages by going directly to the relevant page URL (more details in next section).
-
## Customize the page URL
-By default, the page URL is automatically generated based on the `id` of the page. For example, if `id="This is my first page"`
-the generated page URL will be `path=this-is-my-first-page`. You can then access the page via `localhost:
diff --git a/vizro-core/examples/visual-vocabulary/README.md b/vizro-core/examples/visual-vocabulary/README.md
index 3b298520e..e59b3103c 100644
--- a/vizro-core/examples/visual-vocabulary/README.md
+++ b/vizro-core/examples/visual-vocabulary/README.md
@@ -2,14 +2,11 @@
### Welcome to our visual vocabulary dashboard! 🎨
-This dashboard serves as a comprehensive guide for selecting and creating various types of charts. It helps you decide
-when to use each chart type, and offers sample Python code using [Plotly](https://plotly.com/python/), and
-instructions for embedding these charts into a [Vizro](https://github.com/mckinsey/vizro) dashboard.
+This dashboard serves as a comprehensive guide for selecting and creating various types of charts. It helps you decide when to use each chart type, and offers sample Python code using [Plotly](https://plotly.com/python/), and instructions for embedding these charts into a [Vizro](https://github.com/mckinsey/vizro) dashboard.
The charts in this dashboard are designed to make it easy for anyone to create beautiful and sophisticated visuals.
-Our goal is to help you understand best practices in data visualization, ensure your charts effectively communicate
-your message, and streamline the creation of high-quality, interactive visualizations.
+Our goal is to help you understand best practices in data visualization, ensure your charts effectively communicate your message, and streamline the creation of high-quality, interactive visualizations.
Created by:
@@ -19,12 +16,9 @@ Created by:
Inspired by:
-- [The FT Visual Vocabulary](https://github.com/Financial-Times/chart-doctor/blob/main/visual-vocabulary/README.md):
- [Alan Smith](https://github.com/alansmithy), [Chris Campbell](https://github.com/digitalcampbell), Ian Bott,
- Liz Faunce, Graham Parrish, Billy Ehrenberg, Paul McCallum, [Martin Stabe](https://github.com/martinstabe).
+- [The FT Visual Vocabulary](https://github.com/Financial-Times/chart-doctor/blob/main/visual-vocabulary/README.md): [Alan Smith](https://github.com/alansmithy), [Chris Campbell](https://github.com/digitalcampbell), Ian Bott, Liz Faunce, Graham Parrish, Billy Ehrenberg, Paul McCallum, [Martin Stabe](https://github.com/martinstabe).
-- [The Graphic Continuum](https://www.informationisbeautifulawards.com/showcase/611-the-graphic-continuum):
- Jon Swabish and Severino Ribecca
+- [The Graphic Continuum](https://www.informationisbeautifulawards.com/showcase/611-the-graphic-continuum): Jon Swabish and Severino Ribecca
Credits and sources:
@@ -102,13 +96,12 @@ The dashboard is still in development. Below is an overview of the chart types f
Contributions are welcome! To contribute a chart, follow the steps below:
1. Check that a `svg` file named after the chart type is contained in the [assets](https://github.com/mckinsey/vizro/tree/main/vizro-core/examples/visual-vocabulary/assets/images/charts) folder. If not, [raise an issue](https://github.com/mckinsey/vizro/issues) in the repository.
-2. Add a `.py` file containing a code example of the chart type in the `pages/examples` folder, for instance, `area.py`. Take a look at existing examples.
-3. Create a new page for the chart type and add it to the relevant category `.py` file such as `correlation.py`,
- `deviation.py`, `distribution.py`, etc. Ensure you add the page to the list of `pages` at the end of the `.py` file.
-4. Remove the `IncompletePage(..)` entry for that chart type in `chart_groups.py`.
-5. Update this `README.md` with the new chart type, its status, category, and API links.
+1. Add a `.py` file containing a code example of the chart type in the `pages/examples` folder, for instance, `area.py`. Take a look at existing examples.
+1. Create a new page for the chart type and add it to the relevant category `.py` file such as `correlation.py`, `deviation.py`, `distribution.py`, etc. Ensure you add the page to the list of `pages` at the end of the `.py` file.
+1. Remove the `IncompletePage(..)` entry for that chart type in `chart_groups.py`.
+1. Update this `README.md` with the new chart type, its status, category, and API links.
## How to run the example locally
1. Run the example with the command `hatch run example visual-vocabulary`.
-2. You should now be able to access the app locally via http://127.0.0.1:8051/.
+1. You should now be able to access the app locally via http://127.0.0.1:8051/.