This page explains the multiple layouts components and all the options to control the layout of the dashboard.
There are 4 main components of Jupyter-flex Dashboard: Pages, Sections, Cards and Cells and they have that same hierarchy meaning that Pages contain one or more Sections, Sections contain or or multiple Cards and Cards contain one or multiple cells.
Cells are pretty self explanatory as they are the same as in Jupyter.
A Card is an object that holds one or more Cells, these can be markdown cells or output cells that have outputs such as plots, text, widgets and more.
To define a new Card you use a level-3 markdown header (###
). Each card belongs in a Section and one Section can have one or more Cards.
Any tagged cell (markdown or code) will be added to the current Card until a new Card, Section or Page is defined.
The components of a Card are:
###
) used to define the Cardbody
body
that contain some narrative for the dashboardfooter
help
For example this notebook with one Card, two plots and some text. Note that code cells get expanded to ocupy all the space in the Card while text cells get just use the space they need.
import plotly
import plotly.express as px
df = px.data.iris()
### Card header
"This is a markdown cell, **all** *regular* syntax ~~should~~ works."
"This is another markdown cell, you can add multiple markdown cells and the main chart is expanded."
fig = px.scatter(df, x="sepal_width", y="sepal_length")
fig.show()
"This is more markdown below the main content"
"Click on the help button in the corner to open the help modal."
"This is the help modal, the title above ^^ is the same card header and this is just a regular markdown cell."
"This is code output"
"You can have also have plots here"
fig = px.scatter(df, x="sepal_width", y="sepal_length")
fig.show()
A Section is an object that holds one or more Cards, those Cards can be shown as rows (default) or columns inside the Section.
To define a new Section you use a level-2 markdown header (##
). Each Section belongs in a Page and one Page can have one or more Sections.
The default orientation of Sections in a Page is to show each section as a column.
For example this Notebook with two Sections, the first with one Card and the second one with two:
## Column 1
### Single column
# code
## Column 2
### Sub Plot 1
# code
### Sub Plot 2
# code
The default orientations are columns
for Sections and rows
for Cards. This means that each Section, will be shown as a column and Cards in a Section will be shown as rows.
Each Section default parameters can be overwritten by adding tags to the Section cell (the one with a level-2 header: ##
).
For example in the last Notebook to make the second Section (right column) to also be divided by colums, instead of the defualt of rows, we add an orientation=columns
tag like this:
## Column 2
To change the orientation of Sections in a Page use the global flex_orientation
parameter.
The default is to use the oposite orientation between Sections and Cards as follows:
columns
(default), then section orientation is rows
rows
, then section orientation is columns
To set the globa parameters you tag one code Cell in the Notebook with parameters
.
The parameters
tag
For example adding the following cell as the first cell of the Notebook we had before:
flex_orientation = "rows"
You might have noticed that by default all the Cards in a Section and Sections in a Page are divided equally. If there are 2 Cards in a Section each Card will get 50% of the space, if there are 3 Cards in one Section each will get 33.3% of the space and so on.
This also applied for multiple Sections in one Page.
This proportions can be controlled using the size={value}
tag in Sections and Cards cells.
For example take this notebook that focuses most of the dashboard space on the top Section with one Card.
flex_orientation = "rows"
## Row 1
### Main plot
# code
## Row 2
### Subplot 1
# code
### Subplot 2
# code
What does the value of size mean?
The values for the size
parameter are passed directly to the flex-grow
and flex-shrink
CSS properties.
The default value is 500 so all sections and cards get the same space compared to its sibilings.
An easy way to change this proportions is to make all size
values in a Section add to 1000 (or a simple round number), that way you can calculate the proportions easily.
In the same way that you can control Section proportions in a Page, you can control the Card proportions inside a Section using the size
parameter as a tag in the Card header (level-3 markdown header: ###
).
In the last example if we change these two cells:
### Subplot 1
### Subplot 2
You can make a Section display all it's Cards as tabs, making each Card a tab, allowing you to get more screen space for each Card. Tabs are especially useful when you have a large number of components to display.
To do this just tabs
tag to Section header cell (the one with the level-2 markdown header: ##
).
Tabs animation and header fill
By default Jupyter-flex applies a small fade transition when changing tabs and fills the space for the navigation, these defaults can be controlled on each Section with and no-nav-fill
and no-fade
tags respectively.
For example this notebook:
## Column 1
### First
1
### Second
2
## Column 2
### A
"A"
### B
"B"
### C
"C"
For more complex dashboards with a lot components you can divide the dashboard into multiple pages using level-1 markdown headers (#
).
A Page is an object that holds one or more Sections, those Sections can be shown as columns (default) or rows inside the Page.
If more than one of these headers are present, the main navigation of the dashboard will include each Page title as its own top-level navigation tab.
Page parameters, such as orientation and size, can be overwritten as one would do for Sections by just tagging the level-1 markdown header cell.
A simple example Notebook with 2 Pages and multiple sections, including tabs:
# Page 1
## Col 1
"Page 1 - Col 1 - Plot 1"
## Col 2
### Col 2 - Tab 1
"Page 1 - Col 2 - Tab 1"
### Col 2 - Tab 1
"Page 1 - Col 2 - Tab 2"
# Page 2
## Row 1
"Page 2 - Row 1"
## Row 2
"Page 2 - Row 2"
Sidebars are just one special type of Section and Page, they behave in the same way as regular Section, they can contain one or more cards with markdown or outputs.
If you tag a Page with sidebar
it will be a global Sidebar, meaning that all pages will have the same sidebar.
If you a Section with sidebar
then it will only appear when that particular Page is selected.
This is mostly useful when defining inputs and using ipywidgets, see Voila and Widgets but it can also be used to display other type of information.
Lets take this example with 2 pages, the first one being tagged with sidebar
### This is the global sidebar of the dashboard
"This content is a regular Card, for example *this* **is** [markdown](https://daringfireball.net/projects/markdown/)."
### This is another card
"Since we have to cards in the sidebar the content was split 50/50 by default as it happens in Sections but it can be controlled by tags."
# Page 1
### This is the first page
### Page 1 text
"Page 1 code"
# Page 2
### This is the second page
"Page 2 code"
If you want a sidebar that is only available to one of the Pages, just tag with sidebar
one of the section in that page.
# Page 1
### This is the sidebar of page 1
"This sidebar only appears of page 1, page 2 doesn't have a sidebar."
## Page 2
### This page doesn't have a sidebar
By default Jupyter-flex components are laid out to automatically fill the height of the browser. So that multiple components (Sections, Cards) get expanded to the available space and there is no vertical scrollbar in the body.
This is a good default that works well for a small to medium number of charts, however if you have lots of charts you’ll probably want to scroll rather than fit them all onto the page.
You can control this behavior using the flex_vertical_layout
option. Specify fill
to vertically re-size charts so they completely fill the page and scroll
to layout charts at their natural height, scrolling the page if necessary. For example:
flex_vertical_layout = "scroll"
This part has quick links to all the examples shown in this page and other. Creativity is the limit!