diff --git a/docs/dashboards/_dynamic-title.md b/docs/dashboards/_dynamic-title.md new file mode 100644 index 0000000000..e0f58b7330 --- /dev/null +++ b/docs/dashboards/_dynamic-title.md @@ -0,0 +1,35 @@ +::: {.panel-tabset} + +## Python + +```` {.python .pymd} +```{{python}} +from ipyleaflet import Map, basemaps, basemap_to_tiles + +lat = 48 +long = 350 + +print("title=", f"World Map at {lat}, {long}") + +Map(basemap=basemap_to_tiles(basemaps.OpenStreetMap.Mapnik), + center=(lat, long), zoom=2) +``` +```` + +## R + +````{.markdown} +```{{r}} +library(leaflet) + +lat <- 48 +long <- 350 + +cat("title=", "World Map at", lat, long) + +leaflet() |> addTiles() |> + setView(long, lat, zoom = 2) +``` +```` + +::: diff --git a/docs/dashboards/_learning-more.md b/docs/dashboards/_learning-more.md index 64f68bc7b8..a954ce3013 100644 --- a/docs/dashboards/_learning-more.md +++ b/docs/dashboards/_learning-more.md @@ -4,10 +4,10 @@ [Examples](examples/index.qmd) provides a gallery of example dashboards you can use as inspiration for your own. -[Theming](theming.qmd) describes the various way to customized the fonts, colors, layout and other aspects of dashboard apperance. +[Theming](theming.qmd) describes the various way to customize the fonts, colors, layout and other aspects of dashboard appearance. [Parameters](parameters.qmd) explains how to create dashboard variants by defining parameters and providing distinct values for them on the command line. -[Deployment](deployment.qmd) covers how to deploy both static dashboards (which do not require a server but rather only a web host) and Shiny dashboards (which require a Shiny Server). +[Deployment](deployment.qmd) covers how to deploy both static dashboards (which require only a web host, but not a server) and Shiny dashboards (which require a Shiny Server). Interactive dashboards are covered in the articles on using [Shiny for Python](interactivity/shiny-python/index.qmd), [Shiny for R](interactivity/shiny-r.qmd), and [Observable JS](interactivity/observable.qmd). diff --git a/docs/dashboards/_valuebox-colors.md b/docs/dashboards/_valuebox-colors.md index 301e8fae51..9531ec72fb 100644 --- a/docs/dashboards/_valuebox-colors.md +++ b/docs/dashboards/_valuebox-colors.md @@ -1,10 +1,10 @@ -| Color Alias | Theme Color(s) | -|-------------|----------------| -| `primary` | Blue | -| `secondary` | Gray | -| `success` | Green | -| `info` | Bright Blue | -| `warning` | Yellow/Orange | -| `danger` | Red | -| `light` | Light Gray | -| `dark` | Black | +| Color Alias | Default Theme Color(s) | +|-------------|------------------------| +| `primary` | Blue | +| `secondary` | Gray | +| `success` | Green | +| `info` | Bright Blue | +| `warning` | Yellow/Orange | +| `danger` | Red | +| `light` | Light Gray | +| `dark` | Black | diff --git a/docs/dashboards/components.qmd b/docs/dashboards/components.qmd index 6fdde88be4..2475649f36 100644 --- a/docs/dashboards/components.qmd +++ b/docs/dashboards/components.qmd @@ -9,9 +9,9 @@ Dashboards are compositions of components used to provide navigation and present ## Navigation -All dashboards include a top-level navigation bar that provide a title and (optionally) a logo and author. Dashboards with multiple pages also contain a link to each page on the navigation bar: +All dashboards include a top-level navigation bar that provide a title and (optionally) a logo and author. Dashboards with [multiple pages](#pages) also contain a link to each page on the navigation bar: -![](images/navigation-toolbar.png) +![](images/navigation-toolbar.png){fig-alt="Screenshot of a dashboard navigation bar. The bar begins with a logo of three penguins, then the title Palmer Penguins followed by the author Cobblepot Analytics. There are also three links to pages: Bills, Flippers and Data."} The `title` and `author` are specified as they are with normal documents. You can also include a `logo` and one or more `nav-buttons`: @@ -66,23 +66,20 @@ format: dashboard ::: ::: g-col-7 -![](images/chart-focal-top.png) +![](images/chart-focal-top.png){fig-alt="A schematic of a page layout showing Chart 1 at the top using the full page width, then Chart 2 and Chart 3 side by side in a row below it."} ::: ::: -Here, level 2 markdown headings (e.g. `## Row {height=70%}`) define the contents of rows as well as their relative height. The ```` ```{python} ```` code cells in turn automatically create cards that are laid out in columns within the row. +Here, level 2 markdown headings (e.g. `## Row {height=70%}`) define the contents of rows as well as their relative height. The ```` ```{python} ```` code cells in turn automatically create cards that are laid out in columns within the row. -### Fill vs. Flow -Each row in your dashboard that is not given an explicit height will determine its size by either filling available space or by flowing to its natural height. Filling layout is generally the default, however for certain types of content (e.g. markdown text) flow layout is the default. +::: {.callout-note} -If the default behavior isn't what you want, you can explicitly specify filling or flowing behavior usign the `.fill` and `.flow` classes applied to a row. For example: +## Heading text isn't required -````{.python .pymd} -## Row {.fill} +Although markdown headings are used to define the layout of rows and columns in Quarto dashboards, the heading text itself is discarded. We use the headings `Row` and `Column` in these docs to aid understanding of the layouts, but you can use more descriptive headings if they help you navigate your source code. -## Row {.flow} -```` +::: ### Orientation @@ -114,10 +111,24 @@ format: ::: ::: g-col-7 -![](images/chart-focal-left.png) +![](images/chart-focal-left.png){fig-alt="A schematic of a page layout showing Chart 1 on the left using the full page height, and on the right Chart 2 and Chart 3 are one above the other."} ::: ::: +### Fill vs. Flow + +Each row in your dashboard that is not given an explicit height will determine its size by either filling available space or by flowing to its natural height. Filling layout is generally the default, however for certain types of content (e.g. markdown text) flow layout is the default. + +If the default behavior isn't what you want, you can explicitly specify filling or flowing behavior usign the `.fill` and `.flow` classes applied to a row. For example: + +````{.python .pymd} +## Row {.fill} + +## Row {.flow} +```` + + + ### Scrolling By default, dashboard content fills all available space in the page. You can alternatively specify the `scrolling: true` option to layout content using its natural height and scroll to accommodate page overflow. For example: @@ -144,7 +155,7 @@ format: ::: ::: g-col-7 -![](images/chart-stack-scrolling.png) +![](images/chart-stack-scrolling.png){fig-alt="A schematic of a dashboard layout showing three charts stacked vertically."} ::: ::: @@ -154,7 +165,7 @@ The article on [Dashboard Layouts](layouts.qmd) provides extensive additional ex ## Pages {#pages} -The layout examples above demonstrated only single-page dashboards. To introduce multiple pages, use level 1 headings above the level 2 headings used to define rows and columns. For example, here is a dashboard that splits content across two pages: +The layout examples above demonstrated only single-page dashboards. To introduce multiple pages, use level 1 headings above the level 2 headings used to define rows and columns. The text of the level 1 headings will be used to link to the pages in the navigation bar. For example, here is a dashboard that splits content across two pages: ```` {.python .pymd} --- @@ -187,7 +198,7 @@ Note that we can set a per-page orientation by adding an `orientation` attribute ## Tabsets {#tabsets} -Use tabsets to include multiple views of data or to include content of secondary importance without having it crown the main display. Tabsets are created by adding the `.tabset` class to a row or column. For example, this layout displays the bottom row as a set of two tabs. +Use tabsets to include multiple views of data or to include content of secondary importance without having it crowd the main display. Tabsets are created by adding the `.tabset` class to a row or column. For example, this layout displays the bottom row as a set of two tabs. ::: {.chart-example .grid} ::: g-col-5 @@ -215,11 +226,11 @@ format: dashboard ::: ::: g-col-7 -![](images/chart-tabset-row.png) +![](images/chart-tabset-row.png){fig-alt="Schematic of a dashboard layout showing Chart 1 at the top using the full page width. Below Chart 1, a panel with two tabs is shown: the Chart 2 tab is selected and occupies the full page width; the Chart 3 tab is unselected."} ::: ::: -You can include tabsets at arbitrarily deep levels. Here we include a tabset within a column of a top level row. Each cell within the tabset column becomes a tab. +You can include tabsets at arbitrarily deep levels. Here we include a tabset within a column of a top level row: ::: {.chart-example .grid} ::: g-col-5 @@ -254,13 +265,13 @@ format: dashboard ::: ::: g-col-7 -![](images/chart-tabset-card.png) +![](images/chart-tabset-card.png){fig-alt="Schematic of a dashboard layout showing Chart 1 at the top using the full page width. The row below Chart 1 is split into two columns. In the left column is a panel with two tabs: Chart 2 and Chart 3. In the right column is Chart 4."} ::: ::: -We provide navigational titles for our tabs by adding a `title` option to the cell used to produce each tab. +Each cell within the tabset column becomes a tab, and we provide navigational titles for our tabs by adding a `title` option to the cell used to produce each tab. -Note that you can also have tabs that contain only markdown. To do this use a `::: {.card}` div and include a `title` attribute for the tab: +You can also have tabs that contain only markdown. To do this use a `::: {.card}` div and include a `title` attribute for the tab: ````python ::: {.card title="My Title"} @@ -268,7 +279,7 @@ Card text ::: ```` -In the examples above, each tab include a single card. If you want tabs to contain multiple cards, you can introduce another level of tab headings, each of which can contain multiple cards. For example: +In the examples above, each tab included a single card. If you want tabs to contain multiple cards, introduce another level of headings below the tabset row or column. For example: ````{.python .pymd} --- @@ -323,7 +334,7 @@ This text will be displayed within a card ``` ```` -Note that if you want to provide a title for a markdown card use the `title` attribute. For example: +To provide a title for a markdown card use the `title` attribute. For example: ````python ::: {.card title="My Title"} @@ -331,15 +342,15 @@ This text will be displayed within a card ::: ```` -Note that if you are authoring within a Jupyter Notebook then markdown cells automatically become `.content` divs. +Note that if you are authoring within a Jupyter Notebook then markdown cells automatically become `.card` divs. -In the section on [Cell Output](data-presentation.qmd#cell-output) there are additional details on how cells and their content are mapped to cards (e.g. excluding cells, cells with multiple outputs, etc.). +For additional details on how cells and their content are mapped to cards (e.g. excluding cells, cells with multiple outputs, etc.), see [Cell Output](data-presentation.qmd#cell-output). ### Display Options By default, cards are displayed with no title and a small bit of padding around the edges. Here is a card that displays a [Leaflet](https://ipyleaflet.readthedocs.io) map: -![](images/leaflet-card.png) +![](images/leaflet-card.png){fig-alt="Screenshot of a map inset from a light grey border around the card."} You can add a title to a card by including the `title` cell option. You can also customize the padding using the `padding` option. For example, here we add a title and remove the padding entirely: @@ -353,32 +364,18 @@ Map(basemap=basemap_to_tiles(basemaps.OpenStreetMap.Mapnik), ``` ```` -![](images/leaflet-card-title-padding.png) +![](images/leaflet-card-title-padding.png){fig-alt="Screenshot of a card with the title World Map displayed in the light grey bar at the top. The card contains a map with no inset from the card border."} -You can create a dynamic `title` by printing a `title=` expression as a cell's first output. For example: -```` {.python .pymd} -```{{python}} -from ipyleaflet import Map, basemaps, basemap_to_tiles - -lat = 48 -long = 350 - -print("title=", f"World Map at {lat}, {long}") - -Map(basemap=basemap_to_tiles(basemaps.OpenStreetMap.Mapnik), - center=(lat, long), zoom=2) -``` -```` - -Note that for R you would use the `cat()` rather than `print()` function. +You can create a dynamic `title` by printing a `title=` expression as a cell's first output. For example: +{{< include _dynamic-title.md >}} #### Expanding Cards By default, you can zoom in on the content of cards using the expand button in the bottom right: -![](images/leaflet-card-expandable.png) +![](images/leaflet-card-expandable.png){fig-alt="Screenshot of a card with the cursor hovering over an icon in the bottom right showing the pop up text Expand."} If you don't want cards to be expandable you can specify `expandable: false` (either at the document level or for individual cards). @@ -410,7 +407,7 @@ format: dashboard ::: ::: g-col-7 -![](images/chart-input-sidebar.png) +![](images/chart-input-sidebar.png){fig-alt="Schematic of a dashboard layout showing a sidebar as grey column on the left filling the page height. On the left, Chart 1 and Chart 2 are one above the other."} ::: ::: diff --git a/docs/dashboards/data-presentation.qmd b/docs/dashboards/data-presentation.qmd index 7d21325126..a6c1d2b8dc 100644 --- a/docs/dashboards/data-presentation.qmd +++ b/docs/dashboards/data-presentation.qmd @@ -34,7 +34,7 @@ px.scatter( ``` ```` -![](images/plotly-interactive.png) +![](images/plotly-interactive.png){fig-alt="Screenshot of a card titled GDP and Life Expectancy. The card contains a plot with a set of scatterplots. Below the plot is a slider of years with a play and stop button."} ### matplotlib @@ -51,7 +51,7 @@ plt.rcParams['figure.figsize'] = (12, 3) In the case that your plots are laid out at a wider aspect ratio, setting this option can make a huge difference in terms of using available space. For example, the top plot in the stack below uses the default figure size of 8 x 5 and the bottom one uses the 12 x 3 ratio specified above: -![](images/matplotlib-size.png) +![](images/matplotlib-size.png){fig-alt="Screenshot of a two cards one above the other. The top card contains a plot with large areas of white space on either side. The bottom card contains the same plot but resized to reduce the white space."} Note that the need to explicitly size plots is confined to traditional plotting libraries---if you use Plotly or another JavaScript based plotting system plots will automatically resize to fill their container. @@ -136,14 +136,14 @@ The Python [tabulate](https://github.com/astanin/python-tabulate) package suppor ```{{python}} import pandas as pd from IPython.display import Markdown -penguins = pd.read_csv("penguins.csv")\ +penguins = pd.read_csv("penguins.csv") Markdown(penguins.to_markdown(index=False)) ``` ```` Note that the `index = False` parameter supresses the display of the row index. Here is a card containing output from `tabulate`: -![](images/tabulate.png) +![](images/tabulate.png){fig-alt="Screenshot of a card showing a table of penguins data. The data frame column names appear bold in a row at top. Data rows have a background that alternates between white and grey."} You can also import `tabulate` directly and pass in the object to print directly: @@ -170,7 +170,7 @@ show(penguins) ``` ```` -![](images/itables-scrolling.png) +![](images/itables-scrolling.png){fig-alt="Screenshot of a card showing a table of penguins data. Above the table a Search box appears. The data frame column names appear bold in a row at top and each columns has sorting buttons."} #### Downsampling @@ -213,7 +213,7 @@ knitr::kable(mtcars) ``` ```` -![](images/kable.png) +![](images/kable.png){fig-alt="Screenshot of a card showing a table of penguins data. The data frame column names appear bold in a row at top. Data rows have a background that alternates between white and grey."} Simple markdown tables in dashboards automatically fill their container (scrolling horizontally and vertically as required). @@ -230,7 +230,7 @@ datatable(mtcars) ``` ```` -![](images/dt.png) +![](images/dt.png){fig-alt="Screenshot of a card showing a table of penguins data. Above the table a Search box appears. The data frame column names appear bold in a row at top and each columns has sorting buttons."} #### Options @@ -251,7 +251,7 @@ You can specify alternate options as you like to override these defaults. Value boxes are a great way to prominently display simple values within a dashboard. For example, here is a dashboard row with three value boxes: -![](images/value-boxes.png) +![](images/value-boxes.png){fig-alt="A row of three value boxes. The first has a grey background, a large pencil icon, small text that says Articles per day, and a large number 45. The second has a grey background, a large comment icon, small text that says Comments per day, and a large number 126. The third has a yellow background, a large trashcan icon, small text that says Spam per day, and a large number 50. "} Here is the code you might use to create these value boxes. Note that we use a mix of Python and R cells in this example to illustrate the syntax for each language. Note also that we assume the variables `articles`, `comments`, and `spam` are computed previously within the document. @@ -295,10 +295,12 @@ You can choose between specifying value box options within YAML or within a `dic The `icon` used in value boxes can be any of the 2,000 available [bootstrap icons](https://icons.getbootstrap.com). -The `color` can be any CSS color value, however there are some color aliases that are tuned specifically for dashboards that you might consider using by default: +The `color` can be any CSS color value, however there are some color aliases that are tuned specifically for dashboards that you might consider using by default: {{< include _valuebox-colors.md >}} +While the aliases apply to all [themes](theming.qmd), the colors they correspond to vary. + ### Shiny In a Shiny interactive dashboard you can have value boxes that update dynamically based on the state of the application. The details on how to do this are language-specific: @@ -339,7 +341,7 @@ value_box( ### Markdown Syntax -You can also create value boxes using plain markdown (in which case you'll typically include the value via an inline expression). For example: +You can also create value boxes using plain markdown, in which case you'll typically include the value via an inline expression. For example: ``` {.python .pymd} ## Row @@ -359,9 +361,9 @@ While you often fill dashboard cards with plots and tables, you can also include Here is a dashboard where the last card in a column is plain markdown: -![](images/text-content-column.png){.border} +![](images/text-content-column.png){.border fig-alt="Screenshot of a dashboard with three cards arranged vertically in a column. The first two cards contain plots, the last card contains text that begins 'Gapminder combines data ...'."} -To do this just include a `.content` div alongside the other cells: +To do this just include a `.card` div alongside the other cells: ```` {.python .pymd} ## Column @@ -407,11 +409,11 @@ elsewhere. Learn more about the Gampminder dataset at ::: ```` -![](images/text-content-fused.png){.border} +![](images/text-content-fused.png){.border fig-alt="Screenshot of a single card. The card contains a plot then text below it that begins 'Gapminder combines data...'."} ### Leading Content -Content that is included at the very top of a dashboard (and not explicitly within a `.content` div) is consider leading content, and will be included as is (with no border). For example: +Content that is included at the very top of a dashboard (and not explicitly within a `.content` div) is considered leading content, and will be included as is with no card styling (e.g. with no border). For example: ````{.python .pymd} --- @@ -446,24 +448,13 @@ The output of each computational cell within your notebook or source document wi ### Dynamic Titles -You can create a dynamic `title` by printing a `title=` expression as a cell's first output (in contract to including the `title` as a YAML cell option). For example: - -```` {.python .pymd} -```{{python}} -from ipyleaflet import Map, basemaps, basemap_to_tiles - -print("title=", f"World Map at {lat}, {long}") - -Map(basemap=basemap_to_tiles(basemaps.OpenStreetMap.Mapnik), - center=(lat, long), zoom=2) -``` -```` +You can create a dynamic `title` by printing a `title=` expression as a cell's first output (in contrast to including the `title` as a YAML cell option). For example: -Note that for R you would use the `cat()` rather than `print()` function. +{{< include _dynamic-title.md >}} ### Excluded Cells -Cells that produce no output do not become cards (for example, cells used to import packages, load and filter data, etc. In some cases a cell might produce unexpected output that you want to exclude. To do this add the `output: false` option to the cell: +Cells that produce no output do not become cards (for example, cells used to import packages, load and filter data, etc). If a cell produces unexpected output that you want to exclude add the `output: false` option to the cell: ```` {.python .pymd} ```{{python}} @@ -488,7 +479,7 @@ This behavior corresponds to the `"all"` setting for [Jupyter shell interactivit ### Card Layout -If a cell produces multiple outputs you can use cell layout options to organize their display. For example, here we modify the example of to display plots side-by-side using the `layout-ncol` option: +If a cell produces multiple outputs you can use cell layout options to organize their display. For example, here we modify the example to display plots side-by-side using the `layout-ncol` option: ```` {.python .pymd} ```{{python}} @@ -499,6 +490,6 @@ px.violin(df, x="sex", y="total_bill", color="smoker") ``` ```` -![](images/card-layout-ncol.png) +![](images/card-layout-ncol.png){fig-alt="A screenshot of a dashboard card with the title Tipping behavior showing two plots side by side."} See the article on [Figures](/docs/authoring/figures.qmd#complex-layouts) for additional documentation on custom layouts. \ No newline at end of file diff --git a/docs/dashboards/examples/index.qmd b/docs/dashboards/examples/index.qmd index 68579d6a3f..afd10aa4f0 100644 --- a/docs/dashboards/examples/index.qmd +++ b/docs/dashboards/examples/index.qmd @@ -8,6 +8,5 @@ listing: contents: examples.yml --- - ::: {#examples .column-page-right style="padding-right: 60px;"} ::: diff --git a/docs/dashboards/index.qmd b/docs/dashboards/index.qmd index cec8fe12ff..353fbacf95 100644 --- a/docs/dashboards/index.qmd +++ b/docs/dashboards/index.qmd @@ -35,14 +35,14 @@ Quarto Dashboards make it easy to create interactive dashboards using Python, R, You can create highly customized layouts and use a wide variety of dashboard themes as illustrated in these examples (click to see them in more detail): ::: {layout-ncol="3"} -![](/docs/dashboards/examples/thumbnails/stock-explorer-dashboard.png){.border} +![](/docs/dashboards/examples/thumbnails/stock-explorer-dashboard.png){.border fig-alt="Screenshot of a Stock Trader dashboard: a row of three values boxes, then a row with a stock ticker graph and a table of closing values. Navy blue and green theme."} -![](/docs/dashboards/examples/thumbnails/customer-churn-dashboard.png){.border} +![](/docs/dashboards/examples/thumbnails/customer-churn-dashboard.png){.border fig-alt="Screenshot of a Customer Churn dashboard: a row of three values boxes, then a row with two plots, then a row with a table. Light blue and yellow theme."} -![](/docs/dashboards/examples/thumbnails/penguins-dashboard.png){.border} +![](/docs/dashboards/examples/thumbnails/penguins-dashboard.png){.border fig-alt="Screenshot of a Palmer Penguins dashboard: a sidebar with checkboxes and a dropdown, and two plots in main panel. Blue theme."} ::: -See the [examples gallery](examples/index.qmd) for additional examples and links to source code. +For live versions of these dashboards, source code, and additional examples see the [examples gallery](examples/index.qmd). ## Walkthrough @@ -50,7 +50,7 @@ Here we'll walk through a simple example to illustrate the basics. Then, we'll p This simple single-page Python dashboard uses interactive Plotly visualizations to explore development indicators in the [Gapminder](http://www.gapminder.org/data/) dataset. The dashboard includes two rows, the second of which includes two columns: -![](images/gapminder.png){.border} +![](images/gapminder.png){.border fig-alt="Screenshot of a Development Indicators dashboard: a row titled GDP and Life Expectancy with a single plot, then a row with two plots arranged side by side titled Population and Life Expectancy."} Dashboards consist of several components: @@ -62,7 +62,7 @@ Dashboards consist of several components: Dashboards can be created either using Jupyter notebooks (`.ipynb`) or using plain text markdown (`.qmd`). Here is the code for the notebook version of the above example (click the image for a zoomed view): -![](images/gapminder-jupyter.png){.border} +![](images/gapminder-jupyter.png){.border fig-alt="Screenshot of a gapminder-notebook.ipynb open in Jupyter Lab. After cells for Quarto settings and python setup, there is a markdown cell containing the heading Row, followed by a python code cell generating a plot. Then another markdown cell containing the heading Row, followed by two python code cells each generating a plot."} Here is the plain text `.qmd` version of the dashboard (click on the numbers on the far right for additional explanation of syntax and mechanics): @@ -111,9 +111,9 @@ px.line( ```` 1. The document options define the `title` and `author` for the navigation bar as well as specifying the use of the `dashboard` format. -2. Rows and columns are defined using headers. In this example we define two rows and specify their relative sizes using the `height` option. +2. Rows and columns are defined using headings. In this example we define two rows and specify their relative sizes using the `height` option. 3. Computational cells become cards that live within rows or columns. Cards can have an optional title (which here we specify using the `title` option). -4. The second row includes two computational cells, which are automatically spit into two side by side cards. +4. The second row includes two computational cells, which are automatically split into two side by side cards. ## Getting Started @@ -143,13 +143,11 @@ You can find release notes and installers for all platforms at `//| output: false` option to the first cell: this is to designate the cell as having only intermediate computations (so it should not be turned into a card in the dashboard layout). diff --git a/docs/dashboards/interactivity/shiny-python/_shiny-sidebar.md b/docs/dashboards/interactivity/shiny-python/_shiny-sidebar.md index 1d3b4704c5..d09a1d4cce 100644 --- a/docs/dashboards/interactivity/shiny-python/_shiny-sidebar.md +++ b/docs/dashboards/interactivity/shiny-python/_shiny-sidebar.md @@ -1,5 +1,5 @@ -![](/docs/dashboards/images/shiny-simple.png){.border} +![](/docs/dashboards/images/shiny-simple.png){.border fig-alt="A screenshot of a Penguin Bills dashboard. A sidebar on the left contains two dropdown menus, one for Variable and one for Distribution and a checkbox to show rugmarks. On the right a plot occupies the full page height and shows a histogram of bill_length_mm colored by species."} Here is the source code for this dashboard (click on the numbers on the far right for additional explanation): diff --git a/docs/dashboards/interactivity/shiny-python/index.qmd b/docs/dashboards/interactivity/shiny-python/index.qmd index 65a2ebe916..e7a6f5486f 100644 --- a/docs/dashboards/interactivity/shiny-python/index.qmd +++ b/docs/dashboards/interactivity/shiny-python/index.qmd @@ -29,7 +29,7 @@ We'll start with a very simple dashboard that consists of a single plot and some Next, we'll explore a more in-depth example that covers many of the techniques you'll use when creating dashboards with Shiny, including factoring out setup code, reactive calculations, and more advanced layout constructs like pages. Here is the interactive document we'll be building: -![](../../images/penguins-shiny.png){.border} +![](../../images/penguins-shiny.png){.border fig-alt="Screenshot of a Palmer Penguins dashboard. Navigation bar shows two pages: Plots and Data. On the left is a sidebar with an image of penguins followed by four inputs: a set of checkboxes for Species; a set of checkboxes for Islands; and dropdown for Distribution; and a checkbox to show rug marks. On the right the page is divided into two rows each showing a density plot: the top row of bill_depth_mm; the bottom row of bill_length_mm"} Here is the source code for this dashboard (click on the numbers on the far right for additional explanation of syntax and mechanics): diff --git a/docs/dashboards/interactivity/shiny-python/running.qmd b/docs/dashboards/interactivity/shiny-python/running.qmd index dcd4a8bde7..3a45ae32f0 100644 --- a/docs/dashboards/interactivity/shiny-python/running.qmd +++ b/docs/dashboards/interactivity/shiny-python/running.qmd @@ -19,9 +19,9 @@ We'll cover all of these scenarios in depth here. The [Quarto VS Code Extension](https://marketplace.visualstudio.com/items?itemName=quarto.quarto) provides integrated support for previewing Shiny interactive documents (just use the **Quarto: Preview** command as you normally would with a static document): -![](images/preview-dashboard.png){.border} +![](images/preview-dashboard.png){.border fig-alt="Screenshot of VS Code with the file shiny.qmd open in the left pane. On the right is a pane labelled Quarto Preview showing the live dashboard."} -Note that you need the very latest version of the VS Code extension (v1.105.0 or greater) preview Shiny interactive documents. +Note that you need the very latest version of the VS Code extension (v1.105.0 or greater) to preview Shiny interactive documents. ## Command Line @@ -50,7 +50,7 @@ quarto serve example.qmd You can run an interactive debugging session for Shiny documents by debugging the generated `.py` application file (e.g. `hello-app.py`). Use the **Debug Shiny App** menu command at the top right of the editor to launch a debugging session: -![](images/debug.png){.border} +![](images/debug.png){.border fig-alt="Screenshot of VS Code with the file hello-app.py open. In the top right, a menu is open from the Run dropdown with the Debug Shiny App item selected."} ::: {.callout-caution title="Important Note"} The file you are debugging (e.g. `hello-app.py`) is _generated_ from your interactive document. You should therefore not edit this file directly (as it will be overwritten on the next render) but rather the source document from which it is generated (e.g. `hello.qmd`). diff --git a/docs/dashboards/interactivity/shiny-r.qmd b/docs/dashboards/interactivity/shiny-r.qmd index 3ddd495288..c03df4bfe0 100644 --- a/docs/dashboards/interactivity/shiny-r.qmd +++ b/docs/dashboards/interactivity/shiny-r.qmd @@ -17,7 +17,7 @@ This section covers integrating Shiny with Quarto and assumes that you already h Here we'll explore an in-depth example that covers many of the techniques you'll use when creating dashboards with Shiny, including factoring out setup code, reactive calculations, and more advanced layout constructs like sidebars and tabsets. Here is the interactive document we'll be building: -![](../images/shiny-diamonds.png){.border} +![](../images/shiny-diamonds.png){.border fig-alt="Screenshot of a Diamonds Explorer App. The navigation bar shows two pages: Plot (active), and Data. On the left a sidebar contains eight inputs: a sample size slider; two checkboxes for Jitter and Smooth (both checked); and a dropdown for each of X, Y, Color, Facet Row and Facet Col. On the right, a plot of cut versus carat using points colored by clarity."} Here is the source code for this dashboard (click on the numbers on the far right for additional explanation of syntax and mechanics): diff --git a/docs/dashboards/layouts.qmd b/docs/dashboards/layouts.qmd index ef3dfef9cf..6c27ad438c 100644 --- a/docs/dashboards/layouts.qmd +++ b/docs/dashboards/layouts.qmd @@ -40,7 +40,7 @@ format: dashboard ::: ::: g-col-6 -![](images/chart-stack-fill.png) +![](images/chart-stack-fill.png){fig-alt="Page is split into two equal height rows: Chart 1 is in top row, Chart 2 in bottom row. Dashboard Schematic."} ::: ::: @@ -72,7 +72,7 @@ format: dashboard ::: ::: g-col-6 -![](images/chart-stack-height.png) +![](images/chart-stack-height.png){fig-alt="Page is split into two rows, the top row has a larger height than bottom row. Chart 1 is in top row, Chart 2 in bottom row. Dashboard Schematic."} ::: ::: @@ -103,7 +103,7 @@ format: ::: ::: g-col-6 -![](images/chart-stack-scrolling.png) +![](images/chart-stack-scrolling.png){fig-alt="Page is split into three equal height rows. Chart 1 is in top row, Chart 2 in middle row, Chart 3 in bottom row. Dashboard Schematic."} ::: ::: @@ -135,7 +135,7 @@ format: dashboard ::: ::: g-col-6 -![](images/chart-focal-top.png) +![](images/chart-focal-top.png){fig-alt="Page is split into two rows. The top row has a larger height than the second row. Chart 1 is in the top row and spans the full page width. The bottom row is split into two equal width columns. Chart 3 is in the left column; Chart 4 is in the right column. Dashboard Schematic."} ::: ::: @@ -169,7 +169,7 @@ format: ::: ::: g-col-6 -![](images/chart-focal-left.png) +![](images/chart-focal-left.png){fig-alt="Page is split into two columns. The left column is wider than the right, and contains Chart 1 spanning the full page height. The second column is split into two equal height rows: Chart 2 in the top row, and Chart 3 in the bottom row. Dashboard Schematic."} ::: ::: @@ -204,7 +204,7 @@ format: dashboard ::: ::: g-col-6 -![](images/chart-grid.png) +![](images/chart-grid.png){fig-alt="Page is split into a grid with two equal height rows and two equal width columns. Chart 1 top left; Chart 2 top right; Chart 3 bottom left; Chart 4 bottom right. Dashboard Schematic."} ::: ::: @@ -276,7 +276,7 @@ format: ::: ::: g-col-6 -![](images/chart-tabset-column.png) +![](images/chart-tabset-column.png){fig-alt="Page is split into two equal width columns. The left column has Chart 1 spanning the full page height. The right column has a tabset spanning the full page height: Chart 2 is selected; Chart 3 is unselected. Dashboard Schematic."} ::: ::: @@ -310,7 +310,7 @@ format: dashboard ::: ::: g-col-6 -![](images/chart-tabset-row.png) +![](images/chart-tabset-row.png){fig-alt="Page is split into two equal height rows. The top row has Chart 1 spanning the full page width. The bottom row has a tabset spanning the full page width: Chart 2 is selected; Chart 3 is unselected. Dashboard Schematic."} ::: ::: @@ -351,7 +351,7 @@ format: dashboard ::: ::: g-col-6 -![](images/chart-tabset-card.png) +![](images/chart-tabset-card.png){fig-alt="Page is split into two rows: the first higher than the second. Chart 1 is in the top row and spans the full page width. The bottom row is split into two equal width columns. The left column has a tabset: Chart 2 is selected; Chart 3 is unselected. The right column contains Chart 4. Dashboard Schematic."} ::: ::: @@ -383,7 +383,7 @@ format: dashboard ::: ::: g-col-6 -![](images/chart-input-sidebar.png) +![](images/chart-input-sidebar.png){fig-alt="Page is split into two columns. The column on the left is narrower than the right, and has a grey background representing the sidebar. The column on the right is split into two rows: Chart 1 in the top row; Chart 2 in the bottom row. Dashboard Schematic."} ::: ::: diff --git a/docs/reference/formats/dashboards.qmd b/docs/reference/formats/dashboards.qmd index b2b6b300b5..e97d51937e 100644 --- a/docs/reference/formats/dashboards.qmd +++ b/docs/reference/formats/dashboards.qmd @@ -7,16 +7,17 @@ tbl-colwidths: [25,75] The following document and format options are either dashboard-specific or have special behavior within dashboards (note that in addition to these options all standard [HTML Format](/docs/reference/formats/html.qmd) options are available): -| Option | Description | +| Option | Description | |--------------------------|----------------------------------------------| -| `title` | Title (displayed in top left of navigation bar). | -| `author` | Author (displayed alongside title in smaller font) | -| `logo` | Logo (displayed left of the title in the navigation bar) | -| `orientation` | `rows` or `columns` (default: `rows`) | -| `scrolling` | Use scrolling rather than fill layout? (default: `false`) | -| `expandable` | Make card content expandable (default: `true`) | -| `theme` | Dashboard theme (built in or custom scss) | -| `nav-buttons` | Buttons to appear on the right side oft the navigation bar. Use `linkedin`, `facebook`, `reddit`, `twitter`, `github`, or a custom [Nav Item](/docs/reference/projects/websites.html#nav-items). | +| `title` | Title (displayed in top left of navigation bar) | +| `author` | Author (displayed alongside title in smaller font) | +| `logo` | Logo (displayed left of the title in the navigation bar) | +| `orientation` | `rows` or `columns` (default: `rows`) | +| `scrolling` | Use scrolling rather than fill layout? (default: `false`) | +| `expandable` | Make card content expandable (default: `true`) | +| `theme` | Dashboard theme (built in or custom scss) | +| `nav-buttons` | Buttons to appear on the right side of the navigation bar. Use `linkedin`, `facebook`, `reddit`, `twitter`, `github`, or a custom [Nav Item](/docs/reference/projects/websites.html#nav-items). | + For example: @@ -40,7 +41,7 @@ format: ## Pages -[Pages](/docs/dashboards/components.qmd#pages) can specify a custom orientation that is distinct from the global orientation. +[Pages](/docs/dashboards/components.qmd#pages) can specify a custom orientation that is distinct from the global orientation: | Option | Description | |---------------|-----------------------------------------------------| @@ -59,11 +60,11 @@ format: dashboard ## Sidebars -Create [Sidebars](/docs/dashboards/components.qmd#sidebars) by applying the `.sidebar` attribute to a level 1 heading (for global sidebars) or level 2 heading (for page level sidebars) +Create [Sidebars](/docs/dashboards/components.qmd#sidebars) by applying the `.sidebar` attribute to a level 1 heading (for global sidebars) or level 2 heading (for page level sidebars). | Class | Description | |------------|---------------------------------------------| -| `.sidebar` | Contents should be arranged into a sidebar. | +| `.sidebar` | Contents should be arranged into a sidebar | For example: @@ -78,11 +79,11 @@ format: dashboard ## Rows & Columns -Rows and columns support options for customizing their layout and sizing behavior. The following classes can be used to modify layout behavior. +Rows and columns support options for customizing their layout and sizing behavior. The following classes can be used to modify layout behavior: | Class | Description | -|---------------------|---------------------------------------------------| -| `.tabset` | Contents should be arranged into a [Tabset](/docs/dashboards/components.qmd#tabsets). | +|--------------------|----------------------------------------------------| +| `.tabset` | Contents should be arranged into a [Tabset](/docs/dashboards/components.qmd#tabsets) | | `.fill` | Contents should fill available layout space | | `.flow` | Contents should flow to their natural size | @@ -90,10 +91,10 @@ Note that in most dashboards, `.fill` and `.flow` are determined automatically b The following attributes can be used for explicit sizing: -| Option | Description | +| Option | Description | |--------------------------|----------------------------------------------| -| `width` | Percentage or absolute pixel width (defaults to evenly spaced across row) | -| `height` | Precentage or absolute pixel height (defaults to evenly spaced across column) | +| `width` | Percentage or absolute pixel width (default distributes space evenly across elements in a row) | +| `height` | Percentage or absolute pixel height (default distributes space evenly across elements in a column) | For example: @@ -114,13 +115,13 @@ Note that if some components specify an explicit `width` or `height` and others Card options enable you to specify a title and various layout behaviors: -| Option | Description | +| Option | Description | |--------------------------|----------------------------------------------| -| `title` | Title displayed in card header | -| `padding` | Padding around card content (default: `8px`) | -| `expandable` | Make card content expandable (default: `true`) | -| `width` | Percentage or absolute pixel width (defaults to evenly spaced across row) | -| `height` | Precentage or absolute pixel height (defaults to evenly spaced across column) | +| `title` | Title displayed in card header | +| `padding` | Padding around card content (default: `8px`) | +| `expandable` | Make card content expandable (default: `true`) | +| `width` | Percentage or absolute pixel width (default distributes space evenly across elements in a row) | +| `height` | Percentage or absolute pixel height (default distributes space evenly across elements in a column) | For example: @@ -143,14 +144,14 @@ This is the content. ## Value Boxes -[Value Boxes](/docs/dashboards/components.qmd#value-boxes) support the following options: +[Value Boxes](/docs/dashboards/data-presentation.qmd#value-boxes) support the following options: | Option | Description | |--------------------------|----------------------------------------------| | `title` | Title displayed above value | -| `icon` | Icon id (from [bootstrap icons](https://icons.getbootstrap.com_)). | -| `color` | Background color---this can be any CSS color or one of the theme specific color aliases (see below). | -| `value` | Main display value. | +| `icon` | Icon identifier from [bootstrap icons](https://icons.getbootstrap.com) | +| `color` | Background color---this can be any CSS color or one of the theme specific color aliases (see below) | +| `value` | Main display value | Available themed aliases for `color` include: