improve vignettes for transformers and decorators (#1476)

Some improvements. --------- Signed-off-by: Aleksander Chlebowski <[email protected]> Co-authored-by: Dawid Kałędkowski <[email protected]> Co-authored-by: vedhav <[email protected]>
insightsengineering · Feb 9, 2025 · f1e5311 · f1e5311
1 parent 2fa9ba4
commit f1e5311
Show file tree

Hide file tree

Showing 20 changed files with 687 additions and 300 deletions.
diff --git a/R/dummy_functions.R b/R/dummy_functions.R
@@ -5,7 +5,7 @@
 #' This module creates an object called `object` that can be modified with decorators.
 #' The `object` is determined by what's selected in `Choose a dataset` input in UI.
 #' The object can be anything that can be handled by `renderPrint()`.
-#' See the `vignette("decorate-modules-output", package = "teal")` or [`teal_transform_module`]
+#' See the `vignette("customizing-module-output", package = "teal")` or [`teal_transform_module`]
 #' to read more about decorators.
 #'
 #' @inheritParams teal_modules

diff --git a/R/modules.R b/R/modules.R
@@ -22,7 +22,7 @@ setOldClass("teal_modules")
 #'
 #' # Restricting datasets used by `teal_module`:
 #'
-#' The `datanames` argument controls which datasets are used by the module’s server. These datasets,
+#' The `datanames` argument controls which datasets are used by the module's server. These datasets,
 #' passed via server's `data` argument, are the only ones shown in the module's tab.
 #'
 #' When `datanames` is set to `"all"`, all datasets in the data object are treated as relevant.
@@ -35,7 +35,7 @@ setOldClass("teal_modules")
 #' Please see the _"Hidden datasets"_ section in `vignette("including-data-in-teal-applications").
 #'
 #' # `datanames` with `transformators`
-#' When transformators are specified, their `datanames` are added to the module’s `datanames`, which
+#' When transformators are specified, their `datanames` are added to the module's `datanames`, which
 #' changes the behavior as follows:
 #' - If `module(datanames)` is `NULL` and the `transformators` have defined `datanames`, the sidebar
 #'   will appear showing the `transformators`' datasets, instead of being hidden.

diff --git a/R/teal_transform_module.R b/R/teal_transform_module.R
@@ -23,7 +23,7 @@
 #' To manage these `decorators` within your module, use [`ui_transform_teal_data()`] and [`srv_transform_teal_data()`].
 #' (For further guidance on managing decorators, refer to `ui_args` and `srv_args` in the vignette documentation.)
 #'
-#' See the vignette `vignette("decorate-modules-output", package = "teal")` for additional examples.
+#' See the vignette `vignette("customizing-module-output", package = "teal")` for additional examples.
 #'
 #' # `server` as a language
 #'

diff --git a/_pkgdown.yml b/_pkgdown.yml
@@ -72,12 +72,12 @@ articles:
   - title: Using `teal`
     navbar: Using `teal`
     contents:
-      - teal-as-a-module
+      - teal-as-a-shiny-module
       - teal-options
       - bootstrap-themes-in-teal
   - title: 📃 Technical blueprint
     desc: >
-      The purpose of the blueprint is to aid new developer’s comprehension of the
+      The purpose of the blueprint is to aid new developer's comprehension of the
       fundamental principles of the `teal` framework. We will explore crucial `teal`
       concepts such as data flow, actors, and filter panel, among others.
     contents:

diff --git a/inst/WORDLIST b/inst/WORDLIST
@@ -5,7 +5,6 @@ Hoffmann
 MAEs
 ORCID
 Reproducibility
-Shiny's
 Shinylive
 TLG
 UI

diff --git a/inst/design/teal-app-components-hover.drawio b/inst/design/teal-app-components-hover.drawio
diff --git a/man/example_module.Rd b/man/example_module.Rd
diff --git a/man/teal_modules.Rd b/man/teal_modules.Rd
diff --git a/man/teal_transform_module.Rd b/man/teal_transform_module.Rd
diff --git a/vignettes/adding-support-for-reporting.Rmd b/vignettes/adding-support-for-reporting.Rmd
@@ -39,6 +39,7 @@ interactive <- function() TRUE
 Let us consider an example module, based on the example module from `teal`:
 ```{r module_1}
 library(teal)
+library(teal.reporter)
 
 my_module <- function(label = "example teal module") {
   module(
@@ -138,6 +139,7 @@ if (interactive()) {
 ```{r shinylive_iframe_2, echo = FALSE, out.width = '150%', out.extra = 'style = "position: relative; z-index:1"', eval = requireNamespace("roxy.shinylive", quietly = TRUE) && knitr::is_html_output() && identical(Sys.getenv("IN_PKGDOWN"), "true")}
 code <- paste0(c(
   knitr::knit_code$get("as_interactive"),
+  knitr::knit_code$get("setup"),
   knitr::knit_code$get("module_2"),
   knitr::knit_code$get("app_2")
 ), collapse = "\n")
@@ -206,6 +208,7 @@ The user can now add a card to the report and view it in the `Report previewer`
 ```{r shinylive_iframe_3, echo = FALSE, out.width = '150%', out.extra = 'style = "position: relative; z-index:1"', eval = requireNamespace("roxy.shinylive", quietly = TRUE) && knitr::is_html_output() && identical(Sys.getenv("IN_PKGDOWN"), "true")}
 code <- paste0(c(
   knitr::knit_code$get("as_interactive"),
+  knitr::knit_code$get("setup"),
   knitr::knit_code$get("module_3"),
   knitr::knit_code$get("app_3")
 ), collapse = "\n")
@@ -278,6 +281,7 @@ Now, an application user can see the text added by `custom_function` in the `Rep
 ```{r shinylive_iframe_4, echo = FALSE, out.width = '150%', out.extra = 'style = "position: relative; z-index:1"', eval = requireNamespace("roxy.shinylive", quietly = TRUE) && knitr::is_html_output() && identical(Sys.getenv("IN_PKGDOWN"), "true")}
 code <- paste0(c(
   knitr::knit_code$get("as_interactive"),
+  knitr::knit_code$get("setup"),
   knitr::knit_code$get("module_4"),
   knitr::knit_code$get("app_4")
 ), collapse = "\n")
@@ -318,9 +322,6 @@ This allows `ReporterCard` to store the code necessary to generate the table alo
 To learn more about `teal.code` see the vignette _`qenv`_ in  `teal.code`.
 
 ```{r app_5}
-library(teal)
-library(teal.reporter)
-
 example_reporter_module <- function(label = "Example") {
   module(
     label = label,
@@ -420,7 +421,7 @@ app <- init(
   ),
   filter = teal_slices(teal_slice(dataname = "AIR", varname = "Temp", selected = c(72, 85)))
 ) |>
-  modify_header("Example teal app with reporter")
+  modify_header(tags$h2("Example teal app with reporter"))
 
 if (interactive()) {
   shinyApp(app$ui, app$server)
@@ -430,6 +431,7 @@ if (interactive()) {
 ```{r shinylive_iframe_5, echo = FALSE, out.width = '150%', out.extra = 'style = "position: relative; z-index:1"', eval = requireNamespace("roxy.shinylive", quietly = TRUE) && knitr::is_html_output() && identical(Sys.getenv("IN_PKGDOWN"), "true")}
 code <- paste0(c(
   knitr::knit_code$get("as_interactive"),
+  knitr::knit_code$get("module_1"),
   knitr::knit_code$get("module_5"),
   knitr::knit_code$get("app_5")
 ), collapse = "\n")

diff --git a/vignettes/blueprint/intro.Rmd b/vignettes/blueprint/intro.Rmd
@@ -8,9 +8,9 @@ vignette: >
   %\VignetteEncoding{UTF-8}
 ---
 
-`teal` is an interactive data exploration framework based on Shiny, designed primarily to analyze CDISC clinical trial data.
+`teal` is an interactive data exploration framework based on `shiny`, designed primarily to analyze CDISC clinical trial data.
 
-A Shiny Application created with `teal` offers users the ability to:
+A `shiny` Application created with `teal` offers users the ability to:
 
 - Import data from external sources;
 - Dynamically filter data for analysis;

diff --git a/vignettes/blueprint/module_encapsulation.Rmd b/vignettes/blueprint/module_encapsulation.Rmd
@@ -15,16 +15,16 @@ The `teal` framework leverages the [`shiny` module concept](https://rstudio.gith
 
 ## Benefits
 
-By implementing the modular app technique from the shiny module into the creation of the `teal` module, several benefits are realized:
+By implementing the modular app technique from the `shiny` module into the creation of the `teal` module, several benefits are realized:
 
-1. Streamlined maintenance  
-  The development of the `teal` module becomes more manageable, as it can function independently from the `teal` framework. 
+1. Streamlined maintenance
+  The development of the `teal` module becomes more manageable, as it can function independently from the `teal` framework.
   This separation allows developers to maintain the module with ease. This approach has been successfully applied in `R` packages dedicated to `teal` module development, such as `teal.modules.general` and `teal.modules.clinical`.
 
-1. Enhanced focus on output  
-  `teal` module developers can concentrate solely on refining parameters or encoding, and output aspects (such as data summarization and visualization) without the need to concern themselves with the intricacies of the `teal` framework. 
+1. Enhanced focus on output
+  `teal` module developers can concentrate solely on refining parameters or encoding, and output aspects (such as data summarization and visualization) without the need to concern themselves with the intricacies of the `teal` framework.
   When developed correctly, the module seamlessly integrates with `teal`.
 
-1. Facilitated collaboration  
-  `teal` module development becomes an accessible entry point for developers interested in collaborating. 
+1. Facilitated collaboration
+  `teal` module development becomes an accessible entry point for developers interested in collaborating.
   This approach encourages user collaboration for the improvement of `teal` modules, as developers gain a deeper understanding of the mechanics of the `teal` framework.
diff --git a/vignettes/bootstrap-themes-in-teal.Rmd b/vignettes/bootstrap-themes-in-teal.Rmd
@@ -76,7 +76,7 @@ The most important HTML tags in `teal` have a specific id or class, so they can
 ```
 library(magrittr)
 options("teal.bs_theme" = bslib::bs_add_rules(
-  bslib::bs_theme(version = "5"), 
+  bslib::bs_theme(version = "5"),
   "Anything understood by sass::as_sass()"
 ))
 ```
@@ -175,7 +175,7 @@ if (interactive()) {
 
 Now the application has our custom theme applied.
 
-### Try the above app in Shinylive
+### Try the above app in `shinylive`
 
 ```{r shinylive_iframe, echo = FALSE, out.width = '150%', out.extra = 'style = "position: relative; z-index:1"', eval = requireNamespace("roxy.shinylive", quietly = TRUE) && knitr::is_html_output() && identical(Sys.getenv("IN_PKGDOWN"), "true")}
 code <- paste0(c(

diff --git a/vignettes/creating-custom-modules.Rmd b/vignettes/creating-custom-modules.Rmd
@@ -13,8 +13,8 @@ vignette: >
 ## Introduction
 
 The `teal` framework provides a large catalog of plug-in-ready analysis modules that can be incorporated into `teal` applications.
-However, it is also possible to create your own modules using the module function, which leverages Shiny modules.
-Each custom teal module is built as a Shiny module, combining Shiny's reactive capabilities with modularized UI and server logic to encapsulate functionality.
+However, it is also possible to create your own modules using the `module` function, which leverages `shiny` modules.
+Each custom teal module is built as a [`shiny` module](https://shiny.posit.co/r/articles/improve/modules/), combining `shiny`'s reactive capabilities with modularized UI and server logic to encapsulate functionality.
 This design enables a structured and reusable approach to creating interactive components that integrate seamlessly within the teal ecosystem.
 
 In this guide, we will use the simple histogram below as an example, and demonstrate how to convert this histogram function into a robust `teal` module step-by-step:
@@ -56,11 +56,11 @@ The UI function defines the controls and display area for the histogram.
 For this module, we will use:
 
 - **`selectInput` for Dataset**: Enables users to select a dataset from the list of available datasets.
-- **`selectInput` for Variable**: Allows users to choose a numeric variable from the chosen dataset, dynamically filtering out any non-numeric columns.
+- **`selectInput` for Variable**: Allows users to choose a numeric variable from the chosen dataset, dynamically filtering out any non-numeric variables from the choices.
 - **`plotOutput` for Histogram**: Displays the histogram once both dataset and variable inputs are selected.
-- **`verbatimTextOutput` for Code**: Automatically displays code that generated the plot based on user input.
+- **`verbatimTextOutput` for Code**: Automatically displays code that generated the plot based on the user input.
 
-Here’s the code for the `histogram_module_ui` function:
+Here's the code for the `histogram_module_ui` function:
 
 ```{r module_ui}
 library(teal)
@@ -92,9 +92,9 @@ For our histogram module, the server function will handle user interactions and
 
 ### Passing the `data` Argument to the Server Function
 
-To begin, it’s essential to include the `data` argument in the server function definition.
+To begin, it's essential to include the `data` argument in the server function definition.
 
-This `data` argument holds the reactive `teal_data` object, which contains your datasets and any filters applied. By including `data`, we can ensure:
+This `data` argument holds the reactive `teal_data` object, which contains your datasets after applying any active filtering by the filter panel. By including `data`, we can ensure:
 
 - The server function receives a reactive version of `teal_data`, allowing it to automatically respond to changes.
 - The server can access the filtered datasets directly.
@@ -148,7 +148,7 @@ In this updated server function, we will perform the following:
 1. **Create `new_data`** as a modified version of `data()` using `within()`, dynamically injecting `input$dataset` and `input$variable`.
 2. **Render the Plot**: `renderPlot()` displays the plot by referencing the plot stored in the updated `teal_data` object, `new_data`.
 
-Here’s the code:
+Here's the code:
 
 ```{r module_server}
 # Server function for the custom histogram module with injected variables in within()
@@ -241,7 +241,7 @@ create_histogram_module <- function(label = "Histogram Module") {
 ## Integrating the Custom `teal` Module into a `teal` App
 
 With the custom `teal` module set up, it can now be integrated into a `teal` app.
-We’ll use `init()` from `teal` to specify the datasets and modules used in the app, then run the app to test the newly created module.
+We'll use `init()` from `teal` to specify the datasets and modules used in the app, then run the app to test the newly created module.
 
 ```{r app_init}
 # Define datasets in `teal_data`
@@ -282,12 +282,12 @@ knitr::include_url(url, height = "800px")
 
 ## What's next?
 
-Now that you’ve mastered the essentials of building and integrating modules in `teal`, you’re ready to explore more advanced features.
-`teal` offers a wide range of capabilities to enhance your module’s functionality and user experience.
+Now that you've mastered the essentials of building and integrating modules in `teal`, you're ready to explore more advanced features.
+`teal` offers a wide range of capabilities to enhance your module's functionality and user experience.
 
 ### Adding reporting to a module
 
-Enhance your custom `teal` module with reporting features! Dive into [this vignette](adding-support-for-reporting.html) to see just how simple it is to add powerful reporting capabilities and elevate your module’s impact.
+Enhance your custom `teal` module with reporting features! Dive into [this vignette](adding-support-for-reporting.html) to see just how simple it is to add powerful reporting capabilities and elevate your module's impact.
 
 ### Using standard widgets in your custom module
 The [`teal.widgets`](https://insightsengineering.github.io/teal.widgets/latest-tag/) package provides various widgets which can be leveraged to quickly create standard elements in your custom `teal` module.
-Original file line number
+Diff line change
@@ Expand Up / @@ -5,7 +5,6 @@ Hoffmann @@
     MAEs
     ORCID
     Reproducibility
-    Shiny's
     Shinylive
     TLG
     UI
@@ Expand Down @@