Skip to content

Commit

Permalink
[Feat] Enable variant argument inside Container (#1002)
Browse files Browse the repository at this point in the history
  • Loading branch information
huong-li-nguyen authored Mar 4, 2025
1 parent f12070d commit de81e39
Show file tree
Hide file tree
Showing 14 changed files with 264 additions and 168 deletions.
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
<!--
A new scriv changelog fragment.
Uncomment the section that is right (remove the HTML comment wrapper).
-->

<!--
### Highlights ✨
- A bullet item for the Highlights ✨ category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX. ([#1](https://github.com/mckinsey/vizro/pull/1))
-->
<!--
### Removed
- A bullet item for the Removed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX. ([#1](https://github.com/mckinsey/vizro/pull/1))
-->
### Added

- Enable styling of `vm.Container` with a new argument `theme="plain"/"filled"/"outlined"`. See the user guide on [styled containers](https://vizro.readthedocs.io/en/stable/pages/user-guides/container/#styled-containers) for more details. ([#1002](https://github.com/mckinsey/vizro/pull/1002))

<!--
### Changed
- A bullet item for the Changed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX. ([#1](https://github.com/mckinsey/vizro/pull/1))
-->
<!--
### Deprecated
- A bullet item for the Deprecated category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX. ([#1](https://github.com/mckinsey/vizro/pull/1))
-->
<!--
### Fixed
- A bullet item for the Fixed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX. ([#1](https://github.com/mckinsey/vizro/pull/1))
-->
<!--
### Security
- A bullet item for the Security category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX. ([#1](https://github.com/mckinsey/vizro/pull/1))
-->
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
88 changes: 85 additions & 3 deletions vizro-core/docs/pages/user-guides/container.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

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 a [Page][vizro.models.Page], and both models share nearly identical arguments. While `Page.layout` provides a method for structuring the overall page layout, a `Container` offers more detailed control within a particular section of the 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.
Unlike `Page`, the `Container` includes a `variant` argument. This enables you to choose a style for your container to visually distinguish it from the rest of the page content. Additional functionality will soon be added to the Container, including controls specific to it, which will further enhance the management of 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).
Expand All @@ -24,6 +24,7 @@ Here are a few cases where you might want to use a `Container` instead of `Page.
- If you want to split up your grid into subgrids to organize components together
- If you want to add a title to your subgrids
- If you want different row and column spacing between subgrids
- If you want to apply a background color or borders to visually distinguish your content
- If you want to apply controls to selected subgrids (will be supported soon)

## Basic containers
Expand Down Expand Up @@ -154,7 +155,88 @@ Containers can be nested, providing a hierarchical structure for organizing comp
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()],
)
],
)
```

## Styled containers

To make the `Container` stand out as a distinct section in your dashboard, you can select from the predefined styles available in its `variant` argument.

!!! example "Container with different styles"
=== "app.py"
```{.python pycafe-link}
import vizro.models as vm
import vizro.plotly.express as px
from vizro import Vizro

iris = px.data.iris()

page = vm.Page(
title="Containers with different styles",
layout=vm.Layout(grid=[[0, 1]]),
components=[
vm.Container(
title="Container with background color",
components=[vm.Graph(figure=px.scatter(iris, x="sepal_width", y="sepal_length", color="species"))],
variant="filled"
),
vm.Container(
title="Container with borders",
components=[vm.Graph(figure=px.box(iris, x="species", y="sepal_length", color="species"))],
variant="outlined"
)
],
)

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:
- title: Containers with different styles
layout:
grid: [[0, 1]]
components:
- type: container
title: Container with background color
components:
- type: graph
figure:
_target_: scatter
data_frame: iris
x: sepal_width
y: sepal_length
color: species
variant: filled
- type: container
title: Container with borders
components:
- type: graph
figure:
_target_: box
data_frame: iris
x: species
y: sepal_length
color: species
variant: outlined
```

=== "Result"
[![StyleContainer]][stylecontainer]

If you want to style your `Container` beyond the styling options available inside `variant`, please refer to our user guide on [overwriting CSS for selected components](custom-css.md#overwrite-css-for-selected-components).

[container]: ../../assets/user_guides/components/containers.png
[stylecontainer]: ../../assets/user_guides/components/container-styled.png
91 changes: 1 addition & 90 deletions vizro-core/docs/pages/user-guides/custom-css.md
Original file line number Diff line number Diff line change
Expand Up @@ -295,7 +295,7 @@ It's essential to understand the relationship between the targeted CSS class or

### 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/). 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/).

### Turn off page title

Expand Down Expand Up @@ -351,95 +351,6 @@ By default, the logo appears in the top left corner of the dashboard. You can mo

![Logo positioning](../../assets/user_guides/custom_css/logo-position.png)

### 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`. Chart backgrounds are transparent so they automatically match the background color of the container.

!!! 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;
}

/* 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
import vizro.plotly.express as px
from vizro import Vizro

iris = px.data.iris()

page = vm.Page(
title="Page with subsections",
layout=vm.Layout(grid=[[0, 1]]),
components=[
vm.Container(
title="Container I",
components=[vm.Graph(figure=px.scatter(iris, x="sepal_width", y="sepal_length", color="species"))]
),
vm.Container(
title="Container II",
components=[vm.Graph(figure=px.box(iris, x="species", y="sepal_length", color="species"))]
)
],
)

dashboard = vm.Dashboard(pages=[page])
Vizro().build(dashboard).run()
```

<img src=https://py.cafe/logo.png alt="PyCafe logo" width="30"><b><a target="_blank" href="https://py.cafe/vizro-official/vizro-style-a-container">Run and edit this code in PyCafe</a></b>

=== "app.yaml"
```yaml
# Still requires a .py to add data to the data manager and parse YAML configuration
# See yaml_version example
pages:
- title: Page with subsections
layout:
grid: [[0, 1]]
components:
- type: container
title: Container I
components:
- type: graph
figure:
_target_: scatter
data_frame: iris
x: sepal_width
y: sepal_length
color: species
- type: container
title: Container II
components:
- type: graph
figure:
_target_: box
data_frame: iris
x: species
y: sepal_length
color: species
```

=== "Result"
[![StyleContainer]][stylecontainer]

[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
8 changes: 3 additions & 5 deletions vizro-core/docs/pages/user-guides/layouts.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,7 @@ This defines a single row that occupies the entire width and height, divided int

## 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.
If you need to divide the grid into subgrids for finer control or want to visually distinguish your subgrids, 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.

Expand Down Expand Up @@ -412,11 +412,9 @@ For further customization, such as changing the gap between row and column, refe
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] 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).
[`Tabs`][vizro.models.Tabs] and [`Containers`][vizro.models.Container] provide alternative methods for customizing your page layout. For instance, if you need more granular control, want to break the overall page grid into subgrids, or wish to visually distinguish your subgrid, refer to 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).

![tabs](../../assets/user_guides/components/tabs-info.png){ width="500" }
![tabs](../../assets/user_guides/components/tabs-info.png){ width="500" }

[grid]: ../../assets/user_guides/layout/one_left_two_right.png
[gridadv]: ../../assets/user_guides/layout/grid_advanced.png
Expand Down
89 changes: 47 additions & 42 deletions vizro-core/examples/scratch_dev/app.py
Original file line number Diff line number Diff line change
@@ -1,62 +1,67 @@
"""Test app"""

import vizro.models as vm
import vizro.plotly.express as px
from vizro import Vizro
from vizro.tables import dash_ag_grid
from vizro.models.types import capture
from vizro.figures import kpi_card

tips = px.data.tips()
iris = px.data.iris()

first_page = vm.Page(
title="Data",
page = vm.Page(
title="Page with subsections",
layout=vm.Layout(grid=[[0, 0, 1, 1, 2, 2], [3, 3, 3, 4, 4, 4], [3, 3, 3, 4, 4, 4]]),
components=[
vm.AgGrid(
figure=dash_ag_grid(tips),
footer="""**Data Source:** Bryant, P. G. and Smith, M (1995)
Practical Data Analysis: Case Studies in Business Statistics.
Homewood, IL: Richard D. Irwin Publishing.""",
vm.Card(text="""Hello, this is a card with a [link](https://www.google.com)"""),
vm.Card(text="""Hello, this is a card with a [link](https://www.google.com)"""),
vm.Card(text="""Hello, this is a card with a [link](https://www.google.com)"""),
vm.Container(
title="Container I",
components=[
vm.Graph(figure=px.scatter(iris, x="sepal_width", y="sepal_length", color="species")),
],
variant="outlined",
),
vm.Container(
title="Container II",
components=[
vm.Graph(figure=px.scatter(iris, x="sepal_width", y="sepal_length", color="species")),
],
variant="filled",
),
],
)

second_page = vm.Page(
title="Summary",
page_two = vm.Page(
title="Container",
components=[
vm.Figure(
figure=kpi_card(
data_frame=tips,
value_column="total_bill",
agg_func="mean",
value_format="${value:.2f}",
title="Average Bill",
)
vm.Container(
title="Container III",
components=[
vm.Graph(figure=px.scatter(iris, x="sepal_width", y="sepal_length", color="species")),
],
),
vm.Figure(
figure=kpi_card(
data_frame=tips, value_column="tip", agg_func="mean", value_format="${value:.2f}", title="Average Tips"
)
],
)

page_three = vm.Page(
title="Container Style",
components=[
vm.Container(
title="Container I",
components=[
vm.Graph(figure=px.scatter(iris, x="sepal_width", y="sepal_length", color="species")),
],
variant="outlined",
),
vm.Tabs(
tabs=[
vm.Container(
title="Total Bill ($)",
components=[
vm.Graph(figure=px.histogram(tips, x="total_bill")),
],
),
vm.Container(
title="Total Tips ($)",
components=[
vm.Graph(figure=px.histogram(tips, x="tip")),
],
),
vm.Container(
title="Container II",
components=[
vm.Graph(figure=px.scatter(iris, x="sepal_width", y="sepal_length", color="species")),
],
variant="filled",
),
],
)

dashboard = vm.Dashboard(pages=[first_page, second_page])

dashboard = vm.Dashboard(pages=[page, page_two, page_three])

if __name__ == "__main__":
Vizro().build(dashboard).run()
Loading

0 comments on commit de81e39

Please sign in to comment.