From a23db6c3198819b1010f12e38beeef1b9d3bc6a8 Mon Sep 17 00:00:00 2001 From: catalamarti Date: Sun, 6 Oct 2024 00:04:43 +0100 Subject: [PATCH] add background vingette closes #141 --- .Rbuildignore | 3 + .gitignore | 2 + DESCRIPTION | 3 +- R/background.R | 53 +++++--- vignettes/articles/background.Rmd | 194 ++++++++++++++++++++++++++++++ vignettes/background.Rmd | 40 ------ 6 files changed, 236 insertions(+), 59 deletions(-) create mode 100644 vignettes/articles/background.Rmd delete mode 100644 vignettes/background.Rmd diff --git a/.Rbuildignore b/.Rbuildignore index 4bcfe1b..b4f7f73 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -10,3 +10,6 @@ ^codecov\.yml$ ^data-raw$ ^shiny$ +^doc$ +^Meta$ +^vignettes/articles$ diff --git a/.gitignore b/.gitignore index 070d960..eaa64df 100644 --- a/.gitignore +++ b/.gitignore @@ -43,3 +43,5 @@ vignettes/*.pdf docs shiny/ inst/doc +/doc/ +/Meta/ diff --git a/DESCRIPTION b/DESCRIPTION index 6f88a50..3cf529d 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -27,7 +27,8 @@ Imports: dplyr, DT, glue, - omopgenerics (>= 0.2.3), + markdown, + omopgenerics (>= 0.3.1), purrr, rlang, shiny, diff --git a/R/background.R b/R/background.R index 8f8dc54..d07266d 100644 --- a/R/background.R +++ b/R/background.R @@ -23,15 +23,28 @@ cardFromMd <- function(fileName) { metadata <- content$metadata body <- content$body + tmpFile <- tempfile(fileext = ".md") + writeLines(text = body, con = tmpFile) + + # metadata referring to keys + keys <- getCardKeys(metadata) + arguments <- c( # metadata referring to arguments of card metadata[names(metadata) %in% names(formals(bslib::card))], - # metadata referring to keys - getCardKeys(metadata), - # body - list(shiny::markdown(body)) + # content + list( + keys$header, + bslib::card_body(shiny::HTML(markdown::markdownToHTML( + file = tmpFile, fragment.only = TRUE + ))), + keys$footer + ) |> + eliminateNull() ) + unlink(tmpFile) + do.call(bslib::card, arguments) } @@ -61,20 +74,21 @@ extractYamlMetadata <- function(content) { return(list(body = content, metadata = metadata)) } getCardKeys <- function(metadata) { - x <- list() - for (key in backgroundKeywords$keyword) { - if (key %in% names(metadata)) { - y <- paste0( - backgroundKeywords$fun[backgroundKeywords$keyword == key], - "(metadata[[key]])" - ) |> - rlang::parse_expr() |> - rlang::eval_tidy() - x <- c(x, list(y)) - } - } - - return(x) + backgroundKeywords$keyword |> + rlang::set_names() |> + purrr::map(\(x) { + if (x %in% names(metadata)) { + paste0( + backgroundKeywords$fun[backgroundKeywords$keyword == x], + "(metadata[[x]])" + ) |> + rlang::parse_expr() |> + rlang::eval_tidy() + } else { + NULL + } + }) |> + eliminateNull() } createBackground <- function(background) { @@ -109,3 +123,6 @@ defaultBackground <- function(logo = NULL) { '' ) } +eliminateNull <- function(x) { + x[purrr::map_lgl(x, ~ !is.null(.x))] +} diff --git a/vignettes/articles/background.Rmd b/vignettes/articles/background.Rmd new file mode 100644 index 0000000..31e3eda --- /dev/null +++ b/vignettes/articles/background.Rmd @@ -0,0 +1,194 @@ +--- +title: "Edit the background panel of your shiny using `background.md`" +output: + html_document: + theme: + version: 5 +--- + +```{r, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + comment = "#>" +) +``` + +The background panel is triggered when `background = TRUE` argument is used in the `exportStaticApp()` function. If background is set to TRUE a 'background' panel is added and a default 'background.md' file is created. The content of this 'background' panel will be always a card generated with the `cardFromMd()` function using the content of 'background.md'. In this vignette we are going to show different options how to populate the 'background.md' file. + +```{r} +library(omopViewer) +``` + +## General markdown behaviour + +The markdown part is compiled using the function `markdown::markdownToHTML()`, so anything suported by this function can be included in the markdown part. Most commonly used markdown functionalities are: + +- `#` for titles +- `##` for subtitles +- `###` for third level titles, as so on... +- `![](image.png)` to add images. Remember that the root folder is 'shiny/www/' +- `*...*` for italic text. +- `**...**` for bold text. +- `-` for bullet points. + +A simple example: + +```{markdown} +# Introduction + +This shiny *contains information* on: + +- A +- B +- C + +## Images + +The **ohdsi** logo: +![]('ohdsi_logo.svg'){width=100px} +``` + +```{r, echo=FALSE} +text <- paste0('# Introduction + +This shiny *contains information* on: + +- A +- B +- C + +## Images + +The **ohdsi** logo: + +![](', +system.file("logos", "ohdsi_logo.svg", package = "omopViewer"), +'){width=100px}') + +tmpFile <- tempfile(fileext = ".md") +writeLines(text = text, con = tmpFile) +x <- cardFromMd(tmpFile) +unlink(tmpFile) +x +``` + +## Populate `yaml` part + +You can add some metadata to your markdown using the `yaml` on the top. To do so you need to put the metadata between `---`: + +```{markdown} +--- +YAML CONTENT +--- + +BODY CONTENT + +``` + +The `yaml` metadata can contain two types of information: + +- keywords to add elemets to the card. +- arguments of the `bslib::card` function. + +### Keywords + +The following keywords can be used to edit the `bslib::card()` content: + +```{r, echo=FALSE} +omopViewer:::backgroundKeywords |> + dplyr::mutate(`function` = purrr::map2(.data$link, .data$fun, \(x, y) { + shiny::a(href = x, y) |> + as.character() |> + gt::html() + })) |> + dplyr::select(!c("fun", "link")) |> + gt::gt() +``` + +Function column states which is the function that is triggered. Let's see how to add header and footer to our card: + +```{markdown} +--- +header: "Card header" +footer: "Some extra information" +--- +# Introduction + +bla bla bla bla... +``` + +```{r, echo=FALSE} +text <- '--- +header: "Card header" +footer: "Some extra information" +--- +# Introduction + +bla bla bla bla...' + +tmpFile <- tempfile(fileext = ".md") +writeLines(text = text, con = tmpFile) +x <- cardFromMd(tmpFile) +unlink(tmpFile) +x +``` + +### `bslib::card()` arguments + +We can control the arguments of the `bslib::card()` using the metadata included in the yaml file. To include metadata in your background.md file. + +You can check the documentation of [`bslib::card()`](https://rstudio.github.io/bslib/reference/card.html), the supported arguments are those that can be populated using values (not calls to other functions): + +- `full_screen` +- `height` +- `max_height` +- `min_height` +- `fill` +- `class` +- `id` + +For example: + +```{markdown} +---- +header: "My custom card" +id: "my_custom_id" # this can be later used in the css +class: "my_custom_class" # this can be later used in the css +height: 100px +---- +# Introduction + +This shiny *contains information* on: + +- A +- B +- C +``` + +```{r, echo=FALSE} +text <- paste0('---- +header: "My custom card" +id: "my_custom_id" # this can be later used in the css +class: "my_custom_class" # this can be later used in the css +height: 200px +---- +# Introduction + +This shiny *contains information* on: + +- A +- B +- C') + +tmpFile <- tempfile(fileext = ".md") +writeLines(text = text, con = tmpFile) +x <- cardFromMd(tmpFile) +unlink(tmpFile) +x +``` + +Let's see the html so we can see that id and class are populated: +```{r, echo=FALSE} + x |> as.character() |> cat() +``` + diff --git a/vignettes/background.Rmd b/vignettes/background.Rmd deleted file mode 100644 index a3eae9a..0000000 --- a/vignettes/background.Rmd +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: "Edit the background panel of your shiny using `background.md`" -output: rmarkdown::html_vignette -vignette: > - %\VignetteIndexEntry{background} - %\VignetteEngine{knitr::rmarkdown} - %\VignetteEncoding{UTF-8} ---- - -```{r, include = FALSE} -knitr::opts_chunk$set( - collapse = TRUE, - comment = "#>" -) -``` - -The background panel is triggered when `background = TRUE` argument is used in the `exportStaticApp()` function. If background is set to TRUE a 'background' panel is added and a default 'background.md' file is created. The content of this 'background' will be always a card generated with the `cardFromMd()` function using the content of 'background.md'. In this vignette we are going to show different options how to populate the 'background.md'. - -```{r} -library(omopViewer) -``` - -## `bslib::card()` arguments - -We can control the arguments of the `bslib::card()` using the - -## Keywords - -The following keywords can be used to edit the `bslib::card()` content: - -```{r, echo=FALSE} -omopViewer:::backgroundKeywords |> - dplyr::mutate(`function` = purrr::map2(.data$link, .data$fun, \(x, y) { - shiny::a(href = x, y) |> - as.character() |> - gt::html() - })) |> - dplyr::select(!c("fun", "link")) |> - gt::gt() -```