updated arg id description and ui_teal_with_splash description. (#…

…1071)

fixes #1019

I have revised the description of the id parameter to reflect its
current usage, based on how it was previously utilized. Additionally, I
have rephrased the description of ui_teal_with_splash for better clarity
and understanding.

---------

Signed-off-by: kartikeya kirar <[email protected]>
Co-authored-by: Aleksander Chlebowski <[email protected]>

R/init.R

@@ -33,10 +33,8 @@
 #' @param footer (`shiny.tag` or `character(1)`)
 #'   The footer of the app.
 #' @param id (`character`)
-#'   module id to embed it, if provided,
-#'   the server function must be called with [shiny::moduleServer()];
-#'   See the vignette for an example. However, [ui_teal_with_splash()]
-#'   is then preferred to this function.
+#'   Optional string specifying the `shiny` for `teal` in cases it is used as a module
+#'   rather than a standalone `shiny` app. This is a legacy feature.
 #'
 #' @return named list with server and UI function
 #'
@@ -132,11 +130,7 @@ init <- function(data,
   }
 
   ## `filter`
-  checkmate::assert(
-    .var.name = "filter",
-    checkmate::check_class(filter, "teal_slices"),
-    checkmate::check_list(filter, names = "named")
-  )
+  checkmate::check_class(filter, "teal_slices")
 
   ## all other arguments
   checkmate::assert(
@@ -225,9 +219,8 @@ init <- function(data,
   }
 
   # Note regarding case `id = character(0)`:
-  # rather than using `callModule` and creating a submodule of this module, we directly modify
+  # rather than creating a submodule of this module, we directly modify
   # the UI and server with `id = character(0)` and calling the server function directly
-  # rather than through `callModule`
   res <- list(
     ui = ui_teal_with_splash(id = id, data = data, title = title, header = header, footer = footer),
     server = function(input, output, session) {

R/module_teal.R

@@ -27,7 +27,7 @@
 #'
 #' @name module_teal
 #'
-#' @inheritParams ui_teal_with_splash
+#' @inheritParams module_teal_with_splash
 #'
 #' @param splash_ui (`shiny.tag`) UI to display initially,
 #'   can be a splash screen or a `shiny` module UI. For the latter, see
@@ -37,8 +37,7 @@
 #'   returns the `teal_data`, only evaluated once, `NULL` value is ignored
 #'
 #' @return
-#' `ui_teal` returns `HTML` for `shiny` UI module.
-#' `srv_teal` returns `reactive` which returns the currently active module.
+#' Returns a `reactive` expression which returns the currently active module.
 #'
 #' @examples
 #' # use non-exported function from teal

R/module_teal_with_splash.R

@@ -1,23 +1,57 @@
 # This file adds a splash screen for delayed data loading on top of teal
 
-#' UI to show a splash screen in the beginning, then delegate to [srv_teal()]
+#' Add splash screen to `teal` application.
 #'
 #' @description `r lifecycle::badge("stable")`
 #'
-#' The splash screen could be used to query for a password to fetch the data.
-#' [init()] is a very thin wrapper around this module useful for end-users which
-#' assumes that it is a top-level module and cannot be embedded.
-#' This function instead adheres to the `shiny` module conventions.
+#' Displays custom splash screen during initial delayed data loading.
 #'
-#' If data is obtained through delayed loading, its splash screen is used. Otherwise,
-#' a default splash screen is shown.
+#' @details
+#' This module pauses app initialization pending delayed data loading.
+#' This is necessary because the filter panel and modules depend on the data to initialize.
 #'
-#' Please also refer to the doc of [init()].
+#' `teal_with_splash` follows the `shiny` module convention.
+#' [`init()`] is a wrapper around this that assumes that `teal` it is
+#' the top-level module and cannot be embedded.
+#'
+#' Note: It is no longer recommended to embed `teal` in `shiny` apps as a module.
+#' but rather use `init` to create a standalone application.
+#'
+#' @seealso [init()]
 #'
 #' @param id (`character(1)`)
 #'   module id
 #' @inheritParams init
+#' @param modules (`teal_modules`) object containing the output modules which
+#'   will be displayed in the `teal` application. See [modules()] and [module()] for
+#'   more details.
+#' @inheritParams shiny::moduleServer
+#' @return
+#' Returns a `reactive` expression containing a `teal_data` object when data is loaded or `NULL` when it is not.
+#' @name module_teal_with_splash
+#' @examples
+#' teal_modules <- modules(example_module())
+#' # Shiny app with modular integration of teal
+#' ui <- fluidPage(
+#'   ui_teal_with_splash(id = "app1", data = teal_data())
+#' )
+#'
+#' server <- function(input, output, session) {
+#'   srv_teal_with_splash(
+#'     id = "app1",
+#'     data = teal_data(iris = iris),
+#'     modules = teal_modules
+#'   )
+#' }
+#'
+#' if (interactive()) {
+#'   shinyApp(ui, server)
+#' }
+#'
+NULL
+
 #' @export
+#' @rdname module_teal_with_splash
 ui_teal_with_splash <- function(id,
                                 data,
                                 title = build_app_title(),
@@ -61,21 +95,8 @@ ui_teal_with_splash <- function(id,
   )
 }
 
-#' Server function that loads the data through reactive loading and then delegates
-#' to [srv_teal()].
-#'
-#' @description `r lifecycle::badge("stable")`
-#'
-#' Please also refer to the doc of [init()].
-#'
-#' @inheritParams init
-#' @param modules (`teal_modules`) object containing the output modules which
-#'   will be displayed in the `teal` application. See [modules()] and [module()] for
-#'   more details.
-#' @inheritParams shiny::moduleServer
-#' @return `reactive` containing `teal_data` object when data is loaded.
-#' If data is not loaded yet, `reactive` returns `NULL`.
 #' @export
+#' @rdname module_teal_with_splash
 srv_teal_with_splash <- function(id, data, modules, filter = teal_slices()) {
   checkmate::assert_character(id, max.len = 1, any.missing = FALSE)
   checkmate::check_multi_class(data, c("teal_data", "teal_data_module"))

R/teal_data_module.R

@@ -50,9 +50,6 @@
 #' )
 #'
 #' @name teal_data_module
-#'
-#'
-
 #' @seealso [`teal.data::teal_data-class`], [teal.code::qenv()]
 #'
 #' @export

inst/WORDLIST

@@ -1,25 +1,24 @@
 Biomarker
+Forkers
+Hoffmann
+MAEs
+Reproducibility
+TLG
+UI
+UIs
+UX
 cloneable
 customizable
 favicon
 favicons
-Forkers
 funder
-Hoffmann
-JSON
-MAEs
 omics
 pre
 programmatically
 repo
-Reproducibility
 reproducibility
 summarization
 tabsetted
 themer
 theming
-TLG
-UI
-UIs
 uncheck
-UX