From 2fc233a7fb5461c35ae5dbe21e663c35fca5a427 Mon Sep 17 00:00:00 2001 From: Greg Lin Date: Sun, 14 Aug 2022 15:58:53 -0500 Subject: [PATCH] Replace blockquotes with custom callouts --- pkgdown/extra.scss | 35 ++++++ vignettes/building-twitter-followers.Rmd | 22 ++-- vignettes/conditional-styling.Rmd | 8 +- vignettes/cookbook/cookbook.Rmd | 38 ++++-- vignettes/custom-filtering-extra.Rmd | 4 +- vignettes/custom-filtering.Rmd | 14 ++- vignettes/custom-rendering.Rmd | 4 +- vignettes/examples.Rmd | 153 ++++++++++++++--------- vignettes/javascript-api.Rmd | 12 +- vignettes/sticky-columns.Rmd | 8 +- 10 files changed, 202 insertions(+), 96 deletions(-) diff --git a/pkgdown/extra.scss b/pkgdown/extra.scss index 26cdcc7c..8380d528 100644 --- a/pkgdown/extra.scss +++ b/pkgdown/extra.scss @@ -222,6 +222,41 @@ a[href='#main'] { } } +// Custom callouts +.callout { + margin: 1rem 0; + padding: 0.625rem 1.25rem; + border-left: 0.25rem solid #e9ecef; + + &-box { + @extend .callout; + margin: 1.25rem 0; + padding: 1rem 1.25rem; + border: 1px solid #e9ecef; + border-left-width: 0.25rem; + border-radius: 0.25rem; + } + + & > :last-child { + margin-bottom: 0; + } + + &-note { + @extend .callout-box; + border-left-color: #5bc0de; + } + + &-tip { + @extend .callout-box; + border-left-color: #3fb618; + } + + &-warning { + @extend .callout-box; + border-left-color: #f0ad4e; + } +} + .reactable { font-size: 0.875rem; } diff --git a/vignettes/building-twitter-followers.Rmd b/vignettes/building-twitter-followers.Rmd index dede7f94..576eb6be 100644 --- a/vignettes/building-twitter-followers.Rmd +++ b/vignettes/building-twitter-followers.Rmd @@ -218,10 +218,12 @@ Since we're taking over cell rendering with custom render functions, we'll also have to manually format the numbers and percentages now. Custom cell renderers override column formatters, but this may change in the future. -> If you're ever curious to see how an HTML table was made, you can open -> your [browser's developer tools](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_are_browser_developer_tools) -> and inspect the HTML and CSS behind the table. This is how we figured out -> how the bar charts were made, which colors and fonts were used, and so on. +::: {.callout-tip} +**Tip:** If you're ever curious to see how an HTML table was made, you can open +your [browser's developer tools](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_are_browser_developer_tools) +and inspect the HTML and CSS behind the table. This is how we figured out +how the bar charts were made, which colors and fonts were used, and so on. +::: ```{r} library(htmltools) @@ -276,11 +278,13 @@ One way to do this would be to format the labels as fixed-width strings, and use a monospaced font so that each character takes up the same width. (An alternate method is shown in the [Demo Cookbook](cookbook/cookbook.html#units-on-first-row-only).) -> Some fonts have numerals that are all equal in width, but others do not. -> In tables with numeric columns, using a font with tabular or monospaced -> figures can make the numbers easier to align and read. You can learn more -> about the different types of fonts in this article, -> [Proportional vs. Tabular Figures](https://www.fonts.com/content/learning/fontology/level-3/numbers/proportional-vs-tabular-figures). +::: {.callout-note} +**Note:** Some fonts have numerals that are all equal in width, but others do not. +In tables with numeric columns, using a font with tabular or monospaced +figures can make the numbers easier to align and read. You can learn more +about the different types of fonts in this article, +[Proportional vs. Tabular Figures](https://www.fonts.com/content/learning/fontology/level-3/numbers/proportional-vs-tabular-figures). +::: ```{r} reactable( diff --git a/vignettes/conditional-styling.Rmd b/vignettes/conditional-styling.Rmd index 7458a40d..6ad25fb3 100644 --- a/vignettes/conditional-styling.Rmd +++ b/vignettes/conditional-styling.Rmd @@ -178,7 +178,9 @@ colDef( ) ``` -> NOTE: R functions cannot apply styles to aggregated cells. +::: {.callout-note} +**Note:** R functions cannot apply styles to aggregated cells. +::: ### JavaScript functions {#cell-js-functions} @@ -296,7 +298,9 @@ reactable( ) ``` -> NOTE: R functions cannot apply styles to aggregated rows. +::: {.callout-note} +**Note:** R functions cannot apply styles to aggregated rows. +::: ### JavaScript functions {#row-js-functions} diff --git a/vignettes/cookbook/cookbook.Rmd b/vignettes/cookbook/cookbook.Rmd index 2a6fa93e..585c247f 100644 --- a/vignettes/cookbook/cookbook.Rmd +++ b/vignettes/cookbook/cookbook.Rmd @@ -16,7 +16,7 @@ knitr::opts_chunk$set(echo = TRUE) library(reactable) ``` -> A collection of recipes used to create the reactable demos +A collection of recipes used to create the reactable demos. ## Insert links @@ -463,7 +463,9 @@ reactable(ratings, columns = list( ## Show data from other columns -> This example requires reactable v0.3.0 or above. +::: {.callout} +This example requires reactable v0.3.0 or above. +::: To access data from another column, get the current row data using the row index argument in an R render function, or `cellInfo.row` in a @@ -551,7 +553,9 @@ reactable( ### Dynamic totals -> This example requires reactable v0.3.0 or above. +::: {.callout} +This example requires reactable v0.3.0 or above. +::: To update the total when filtering the table, calculate the total in a JavaScript render function: @@ -833,7 +837,9 @@ reactable( ## Borders between groups of data -> This example requires reactable v0.3.0 or above. +::: {.callout} +This example requires reactable v0.3.0 or above. +::: To add borders between groups, use an R or JavaScript function to style rows based on the previous or next row's data. If the table can be sorted, use a @@ -874,7 +880,9 @@ reactable( ## Merge cells -> This example requires reactable v0.3.0 or above. +::: {.callout} +This example requires reactable v0.3.0 or above. +::: You can give the appearance of merged cells by hiding cells based on the previous row's data. Just like with the example above, you'll need a JavaScript @@ -973,13 +981,19 @@ htmltools::tags$link(href = "https://fonts.googleapis.com/css?family=Work+Sans:4 rel = "stylesheet") ``` -> As a side note, the reactable package documentation uses the default system fonts -> installed on your operating system (also known as a -> [system font stack](https://css-tricks.com/snippets/css/system-font-stack)): -> -> ```css -> font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif; -> ``` +::: {.callout-tip} +**Tip:** The reactable package documentation uses the default system fonts +installed on your operating system (also known as a +[system font stack](https://css-tricks.com/snippets/css/system-font-stack)), which +load fast and look familiar: + +```css +font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif; +``` + +[Bootstrap 5 also uses a system font stack](https://getbootstrap.com/docs/5.0/content/reboot/#native-font-stack) +by default. +::: ## Custom sort indicators diff --git a/vignettes/custom-filtering-extra.Rmd b/vignettes/custom-filtering-extra.Rmd index 9a1737df..d68cc7e0 100644 --- a/vignettes/custom-filtering-extra.Rmd +++ b/vignettes/custom-filtering-extra.Rmd @@ -13,8 +13,8 @@ knitr::opts_chunk$set(echo = TRUE) library(reactable) ``` -> More examples of [custom filtering](./custom-filtering.html). Note that the -> examples on this page do not support IE 11. +More examples of [custom filtering](./custom-filtering.html). Note that the +examples on this page do not support IE 11. ## Material UI Range Filter diff --git a/vignettes/custom-filtering.Rmd b/vignettes/custom-filtering.Rmd index e0da10a1..44b77c49 100644 --- a/vignettes/custom-filtering.Rmd +++ b/vignettes/custom-filtering.Rmd @@ -38,7 +38,9 @@ propsTable <- function(props) { } ``` -> New in v0.3.0 +::: {.callout} +New in v0.3.0 +::: Custom filter methods and custom filter inputs let you change how filtering is done in reactable. By default, all filter inputs are text inputs that filter data using @@ -191,10 +193,12 @@ For more information on React or using React from R, see the [React documentation](https://reactjs.org/) and [reactR package documentation](https://react-r.github.io/reactR/index.html). -> **TIP:** Many column filter inputs do not have a visible text label, including -> the default text inputs. If your custom filter does not have a visible text label, -> be sure to give it an accessible name using the -> [`aria-label` attribute or similar technique](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label). +::: {.callout-tip} +**Tip:** Many column filter inputs do not have a visible text label, including +the default text inputs. If your custom filter does not have a visible text label, +be sure to give it an accessible name using the +[`aria-label` attribute or similar technique](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label). +::: ### R render function {#filter-r-render-function} diff --git a/vignettes/custom-rendering.Rmd b/vignettes/custom-rendering.Rmd index 304fde2b..29a4493b 100644 --- a/vignettes/custom-rendering.Rmd +++ b/vignettes/custom-rendering.Rmd @@ -95,7 +95,9 @@ dynamic behavior (e.g., render based on filtered state) or have a very large tab #### Example: column total with filtering -> This example requires reactable v0.3.0 or above. +::: {.callout} +This example requires reactable v0.3.0 or above. +::: For example, you can easily add a column total using an R render function: diff --git a/vignettes/examples.Rmd b/vignettes/examples.Rmd index 2c7cb3a4..a55340ff 100644 --- a/vignettes/examples.Rmd +++ b/vignettes/examples.Rmd @@ -65,8 +65,10 @@ Sorting toggles between ascending and descending order by default. To clear the sort, hold the shift key while sorting, and the sorting will additionally toggle between ascending, descending, and unsorted order. -> Ascending order means the lowest, first, or earliest values will appear first. -> Descending order means the largest, last, or latest values will appear first. +::: {.callout-note} +**Note:** Ascending order means the lowest, first, or earliest values will appear first. +Descending order means the largest, last, or latest values will appear first. +::: ### Default sorted columns @@ -292,12 +294,16 @@ Tables are paginated by default, but you can disable pagination by setting `pagi reactable(iris[1:20, ], pagination = FALSE, highlight = TRUE, height = 250) ``` -> **NOTE:** Disabling pagination is not recommended for large tables with many -> interactive elements (such as links, expand buttons, or selection checkboxes), -> as that can make it difficult for keyboard users to navigate the page. +::: {.callout-tip} +**Tip:** Disabling pagination is not recommended for large tables with many +interactive elements (such as links, expand buttons, or selection checkboxes), +as that can make it difficult for keyboard users to navigate the page. +::: ## Grouping and Aggregation + You can group rows in a table by specifying one or more columns in `groupBy`: + ```{r} data <- MASS::Cars93[10:22, c("Manufacturer", "Model", "Type", "Price", "MPG.city")] @@ -305,6 +311,7 @@ reactable(data, groupBy = "Manufacturer") ``` When rows are grouped, you can aggregate data in a column using an `aggregate` function: + ```{r} data <- MASS::Cars93[14:38, c("Type", "Price", "MPG.city", "DriveTrain", "Man.trans.avail")] @@ -432,7 +439,9 @@ reactable( ### Include sub rows in pagination -> New in v0.3.0 +::: {.callout} +New in v0.3.0 +::: By default, sub rows are excluded from pagination and always shown on the same page when expanded. To include sub rows in pagination, you can set `paginateSubRows` @@ -678,7 +687,9 @@ reactable(data, columns = list( ### Grouped cell rendering -> New in v0.3.0 +::: {.callout} +New in v0.3.0 +::: ```{r} data <- MASS::Cars93[10:22, c("Manufacturer", "Model", "Type", "Price", "MPG.city")] @@ -742,7 +753,9 @@ reactable( ### Header rendering -> This example requires reactable v0.3.0 or above. +::: {.callout} +This example requires reactable v0.3.0 or above. +::: ```{r} library(htmltools) @@ -798,7 +811,9 @@ reactable( #### JavaScript render function -> This example requires reactable v0.3.0 or above. +::: {.callout} +This example requires reactable v0.3.0 or above. +::: ```{r} reactable( @@ -840,7 +855,9 @@ reactable( ## Expandable Row Details -> This example requires reactable v0.3.0 or above. +::: {.callout} +This example requires reactable v0.3.0 or above. +::: You can make rows expandable with additional content through `details`, which takes an R or JavaScript render function. See [Custom Rendering](custom-rendering.html) @@ -896,7 +913,9 @@ reactable(iris[1:5, ], details = function(index) { ### Multiple row details -> This example requires reactable v0.3.0 or above. +::: {.callout} +This example requires reactable v0.3.0 or above. +::: You can add `details` to individual columns, and even show multiple details for a row: @@ -966,7 +985,9 @@ reactable(sleep[1:6, ], columns = list( #### JavaScript style function -> This example requires reactable v0.3.0 or above. +::: {.callout} +This example requires reactable v0.3.0 or above. +::: ```{r} reactable(sleep[1:6, ], columns = list( @@ -1017,7 +1038,9 @@ reactable(sleep[1:6, ], #### JavaScript style function -> This example requires reactable v0.3.0 or above. +::: {.callout} +This example requires reactable v0.3.0 or above. +::: ```{r} reactable(sleep[1:6, ], @@ -1195,7 +1218,9 @@ reactable( ### Vertical alignment -> New in v0.3.0 +::: {.callout} +New in v0.3.0 +::: You can change the vertical alignment of cell content using the `vAlign` or `headerVAlign` arguments in `colDef()` and `colGroup()`. `vAlign` controls the @@ -1299,10 +1324,12 @@ external style sheet: - [Using custom CSS in R Markdown documents](https://bookdown.org/yihui/rmarkdown/html-document.html#custom-css) - [Using custom CSS in Shiny apps](https://shiny.rstudio.com/articles/css.html) -> **NOTE:** If you inspect a table's HTML, you might find CSS classes like `.rt-table` on -> different elements of the table. These CSS classes are undocumented and subject to change, -> so we recommend adding your own custom class names, or using [themes](#theming) to customize -> parts of the table that aren't covered by the custom class names. +::: {.callout-note} +**Note:** If you inspect a table's HTML, you might find CSS classes like `.rt-table` on +different elements of the table. These CSS classes are undocumented and subject to change, +so we recommend adding your own custom class names, or using [themes](#theming) to customize +parts of the table that aren't covered by the custom class names. +::: ## Theming @@ -1469,7 +1496,9 @@ reactable(MASS::Cars93[1:5, ], resizable = TRUE, wrap = FALSE, bordered = TRUE) ## Sticky Columns -> New in v0.3.0 +::: {.callout} +New in v0.3.0 +::: You can make columns sticky when scrolling horizontally using the `sticky` argument in `colDef()` or `colGroup()`. Set `sticky` to either `"left"` @@ -1496,7 +1525,9 @@ reactable( ) ``` -> **NOTE:** Sticky columns are not supported in IE11. +::: {.callout-note} +**Note:** Sticky columns are not supported in IE11. +::: Before v0.3.0, columns could be made sticky by applying custom styles. This method was harder to use and did not work well with column resizing, @@ -1579,7 +1610,9 @@ reactable(iris[1:5, ], rownames = TRUE) ### Row headers -> New in v0.3.0 +::: {.callout} +New in v0.3.0 +::: You can mark up cells in a column as row headers by setting `rowHeader` to `TRUE` in `colDef()`. @@ -1630,7 +1663,9 @@ reactable(iris[1:5, ], selection = "multiple", onClick = "select") ### Custom action -> This example requires reactable v0.3.0 or above. +::: {.callout} +This example requires reactable v0.3.0 or above. +::: This example uses a custom click action to create custom "show details" action buttons in each row of the table: @@ -1671,11 +1706,12 @@ reactable( ) ``` -> **WARNING:** Custom click actions are currently not accessible to keyboard -> users, and are generally not recommended. If they must be used, ensure that -> they can be triggered by a keyboard through other means, such as a button -> in the example above. - +::: {.callout-warning} +**Warning:** Custom click actions are currently not accessible to keyboard +users, and are generally not recommended. If they must be used, ensure that +they can be triggered by a keyboard through other means, such as a button +in the example above. +::: ## Language Options @@ -1777,9 +1813,6 @@ server <- function(input, output, session) { shinyApp(ui, server) ``` -> **NOTE:** `selectionId` can also be used to get the selected rows in Shiny, -> but this will be deprecated in a future release. - #### Default selected rows You can preselect rows by specifying a vector of row indices in `defaultSelected`: @@ -2015,33 +2048,35 @@ shiny::fluidRow( ) ``` -> **NOTE:** This example uses `shiny::fluidRow()` and `shiny::column()` to create -> a Bootstrap grid layout, which works with all Bootstrap versions. `crosstalk::bscols()` -> can also create a grid, but is only compatible with Bootstrap 3. If you're not using -> Bootstrap, here's an alternative way to create a responsive grid using CSS grid. -> ->
-> Example: grid layout using CSS grid -> ```{r, eval=FALSE} -> library(crosstalk) -> -> cars <- MASS::Cars93[1:20, c("Manufacturer", "Model", "Type", "Price")] -> data <- SharedData$new(cars) -> -> div( -> style = "display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 0.75rem;", -> div( -> filter_checkbox("type", "Type", data, ~Type), -> filter_slider("price", "Price", data, ~Price, width = "100%"), -> filter_select("mfr", "Manufacturer", data, ~Manufacturer) -> ), -> div( -> style = "grid-column: span 2;", -> reactable(data, minRows = 10) -> ) -> ) -> ``` ->
+::: {.callout-note} +**Note:** This example uses `shiny::fluidRow()` and `shiny::column()` to create +a Bootstrap grid layout, which works with all Bootstrap versions. `crosstalk::bscols()` +can also create a grid, but is only compatible with Bootstrap 3. If you're not using +Bootstrap, here's an alternative way to create a responsive grid using CSS grid. + +
+Example: grid layout using CSS grid +```{r, eval=FALSE} +library(crosstalk) + +cars <- MASS::Cars93[1:20, c("Manufacturer", "Model", "Type", "Price")] +data <- SharedData$new(cars) + +div( + style = "display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 0.75rem;", + div( + filter_checkbox("type", "Type", data, ~Type), + filter_slider("price", "Price", data, ~Price, width = "100%"), + filter_select("mfr", "Manufacturer", data, ~Manufacturer) + ), + div( + style = "grid-column: span 2;", + reactable(data, minRows = 10) + ) +) +``` +
+::: ### Linked selection @@ -2085,7 +2120,9 @@ htmltools::browsable( ## JavaScript API -> New in v0.3.0 +::: {.callout} +New in v0.3.0 +::: You can use the JavaScript API to create custom interactive controls for your table without the use of Shiny, or add cross-widget interactions beyond what Crosstalk provides. diff --git a/vignettes/javascript-api.Rmd b/vignettes/javascript-api.Rmd index 77936170..293aeee7 100644 --- a/vignettes/javascript-api.Rmd +++ b/vignettes/javascript-api.Rmd @@ -38,7 +38,9 @@ propsTable <- function(props) { } ``` -> New in v0.3.0 +::: {.callout} +New in v0.3.0 +::: ## Introduction @@ -137,9 +139,11 @@ htmltools::browsable( ) ``` -> **NOTE**: `htmltools::browsable()` is a convenient way to view the rendered HTML when -> copying code into the console. It isn't required to render HTML in R Markdown documents -> or Shiny apps. +::: {.callout-note} +**Note:** `htmltools::browsable()` is a convenient way to view the rendered HTML when +copying code into the console. It isn't required to render HTML in R Markdown documents +or Shiny apps. +::: To reuse this button in other tables, you can also convert it into a function that generates download buttons: diff --git a/vignettes/sticky-columns.Rmd b/vignettes/sticky-columns.Rmd index 129f3778..bfc6245e 100644 --- a/vignettes/sticky-columns.Rmd +++ b/vignettes/sticky-columns.Rmd @@ -13,9 +13,11 @@ knitr::opts_chunk$set(echo = TRUE) library(reactable) ``` -> Sticky columns are now supported using a `sticky` argument in `colDef()` -> and `colGroup()`, so use that if possible. -> See [Sticky Columns](./examples.html#sticky-columns) for examples. +::: {.callout-note} +**Note:** Sticky columns are now supported using a `sticky` argument in `colDef()` +and `colGroup()`, so use that if possible. +See [Sticky Columns](./examples.html#sticky-columns) for examples. +::: ### Basic sticky columns