diff --git a/R/teal_transform_module.R b/R/teal_transform_module.R index 9c177bdc14..c6df2f11fe 100644 --- a/R/teal_transform_module.R +++ b/R/teal_transform_module.R @@ -1,32 +1,34 @@ -#' Data module for `teal` transforms. +#' Data module for `teal` transformations and output customization #' #' @description #' `r lifecycle::badge("experimental")` #' -#' `teal_transform_module` creates a shiny-module to transform data in a `teal` application. +#' `teal_transform_module` provides a `shiny` module that enables data transformations within a `teal` application +#' and allows for customization of outputs generated by modules. #' -#' # Transforming `teal` module's input +#' # Transforming Module Inputs in `teal` #' -#' This transformation happens after the data has passed through the filtering activity in teal. The -#' transformed data is then sent to the server of the [teal_module()]. Process is handled by `teal` -#' internals. +#' Data transformations occur after data has been filtered in `teal`. +#' The transformed data is then passed to the `server` of [`teal_module()`] and managed by `teal`'s internal processes. +#' The primary advantage of `teal_transform_module` over custom modules is in its error handling, where all warnings and +#' errors are managed by `teal`, allowing developers to focus on transformation logic. #' -#' See vignette `vignette("data-transform-as-shiny-module", package = "teal")` for more details. +#' For more details, see the vignette: `vignette("data-transform-as-shiny-module", package = "teal")`. #' -#' # Decorating `teal` module's output +#' # Customizing Module Outputs #' -#' `teal_transform_module`'s purpose is to modify any object created in [`teal.data::teal_data`]. It means that an -#' app-developer can use `teal_transform_module` to modify data but also outputted tables, listings and graphs. -#' Some [`teal_modules`] enables app developer to inject custom shiny module to modify displayed output. -#' To handle these `decorators` inside of your module use [ui_transform_data()] and [srv_transform_data]. -#' (todo: write more about how to handle decorators: they need to go through ui_args/srv_args and then be consumed by -#' ui/srv_transform_data()... . Alternatively, decorators could be a [module()]'s argument) +#' `teal_transform_module` also allows developers to modify any object created within [`teal.data::teal_data`]. +#' This means you can use it to customize not only datasets but also tables, listings, and graphs. +#' Some [`teal_modules`] permit developers to inject custom `shiny` modules to enhance displayed outputs. +#' To manage these `decorators` within your module, use [`ui_transform_data()`] and [`srv_transform_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. #' #' # `server` as a language #' -#' Server function in `teal_transform_module` must return `reactive` containing [teal.data::teal_data] object. -#' Consider sinmple transform which doesn't require any advanced reactivity, example `server` might have a -#' following form: +#' The `server` function in `teal_transform_module` must return a reactive [`teal.data::teal_data`] object. +#' For simple transformations without complex reactivity, the `server` function might look like this:s #' #' ``` #' function(id, data) { @@ -42,22 +44,21 @@ #' } #' ``` #' -#' Above can be simplified to presented below, where `level` will be automatically substituted with -#' the respective input matched by its name. +#' The example above can be simplified using `make_teal_transform_server`, where `level` is automatically matched to the +#' corresponding `input` parameter: #' #' ``` -#' make_transform_data(expr = expression(x <- subset(x, col == level))) +#' make_teal_transform_server(expr = expression(x <- subset(x, col == level))) #' ``` #' @inheritParams teal_data_module -#' @param server (`function(id, data)` or `language`) -#' `shiny` module server function; that takes `id` and `data` argument, -#' where the `id` is the module id and `data` is the reactive `teal_data` input. -#' The server function must return reactive expression containing `teal_data` object. -#' To simplify, use [make_teal_transform_server()]. +#' @param server (`function(id, data)` or `expression`) +#' A `shiny` module server function that takes `id` and `data` as arguments, where `id` is the module id and `data` +#' is the reactive `teal_data` input. The `server` function must return a reactive expression containing a `teal_data` +#' object. For simplified syntax, use [`make_teal_transform_server()`]. #' @param datanames (`character`) -#' Names of the datasets that are relevant for the module. The -#' filter panel will only display filters for specified `datanames`. The keyword `"all"` will show -#' filters of all datasets. `datanames` will be automatically appended to the [modules()] `datanames`. +#' Specifies the names of datasets relevant to the module. Only filters for the specified `datanames` will be displayed +#' in the filter panel. The keyword `"all"` can be used to display filters for all datasets. `datanames` are +#' automatically appended to the [`modules()`] `datanames`. #' #' #' @examples diff --git a/man/teal_transform_module.Rd b/man/teal_transform_module.Rd index 4ff69fbc9f..f537170339 100644 --- a/man/teal_transform_module.Rd +++ b/man/teal_transform_module.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/teal_transform_module.R \name{teal_transform_module} \alias{teal_transform_module} -\title{Data module for \code{teal} transforms.} +\title{Data module for \code{teal} transformations and output customization} \usage{ teal_transform_module( ui = NULL, @@ -15,45 +15,46 @@ teal_transform_module( \item{ui}{(\verb{function(id)}) \code{shiny} module UI function; must only take \code{id} argument} -\item{server}{(\verb{function(id, data)} or \code{language}) -\code{shiny} module server function; that takes \code{id} and \code{data} argument, -where the \code{id} is the module id and \code{data} is the reactive \code{teal_data} input. -The server function must return reactive expression containing \code{teal_data} object. -To simplify, use \code{\link[=make_teal_transform_server]{make_teal_transform_server()}}.} +\item{server}{(\verb{function(id, data)} or \code{expression}) +A \code{shiny} module server function that takes \code{id} and \code{data} as arguments, where \code{id} is the module id and \code{data} +is the reactive \code{teal_data} input. The \code{server} function must return a reactive expression containing a \code{teal_data} +object. For simplified syntax, use \code{\link[=make_teal_transform_server]{make_teal_transform_server()}}.} \item{label}{(\code{character(1)}) Label of the module.} \item{datanames}{(\code{character}) -Names of the datasets that are relevant for the module. The -filter panel will only display filters for specified \code{datanames}. The keyword \code{"all"} will show -filters of all datasets. \code{datanames} will be automatically appended to the \code{\link[=modules]{modules()}} \code{datanames}.} +Specifies the names of datasets relevant to the module. Only filters for the specified \code{datanames} will be displayed +in the filter panel. The keyword \code{"all"} can be used to display filters for all datasets. \code{datanames} are +automatically appended to the \code{\link[=modules]{modules()}} \code{datanames}.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} -\code{teal_transform_module} creates a shiny-module to transform data in a \code{teal} application. +\code{teal_transform_module} provides a \code{shiny} module that enables data transformations within a \code{teal} application +and allows for customization of outputs generated by modules. } -\section{Transforming \code{teal} module's input}{ -This transformation happens after the data has passed through the filtering activity in teal. The -transformed data is then sent to the server of the \code{\link[=teal_module]{teal_module()}}. Process is handled by \code{teal} -internals. +\section{Transforming Module Inputs in \code{teal}}{ +Data transformations occur after data has been filtered in \code{teal}. +The transformed data is then passed to the \code{server} of \code{\link[=teal_module]{teal_module()}} and managed by \code{teal}'s internal processes. +The primary advantage of \code{teal_transform_module} over custom modules is in its error handling, where all warnings and +errors are managed by \code{teal}, allowing developers to focus on transformation logic. -See vignette \code{vignette("data-transform-as-shiny-module", package = "teal")} for more details. +For more details, see the vignette: \code{vignette("data-transform-as-shiny-module", package = "teal")}. } -\section{Decorating \code{teal} module's output}{ -\code{teal_transform_module}'s purpose is to modify any object created in \code{\link[teal.data:teal_data]{teal.data::teal_data}}. It means that an -app-developer can use \code{teal_transform_module} to modify data but also outputted tables, listings and graphs. -Some \code{\link{teal_modules}} enables app developer to inject custom shiny module to modify displayed output. -To handle these \code{decorators} inside of your module use \code{\link[=ui_transform_data]{ui_transform_data()}} and \link{srv_transform_data}. -(todo: write more about how to handle decorators: they need to go through ui_args/srv_args and then be consumed by -ui/srv_transform_data()... . Alternatively, decorators could be a \code{\link[=module]{module()}}'s argument) +\section{Customizing Module Outputs}{ +\code{teal_transform_module} also allows developers to modify any object created within \code{\link[teal.data:teal_data]{teal.data::teal_data}}. +This means you can use it to customize not only datasets but also tables, listings, and graphs. +Some \code{\link{teal_modules}} permit developers to inject custom \code{shiny} modules to enhance displayed outputs. +To manage these \code{decorators} within your module, use \code{\link[=ui_transform_data]{ui_transform_data()}} and \code{\link[=srv_transform_data]{srv_transform_data()}}. +(For further guidance on managing decorators, refer to \code{ui_args} and \code{srv_args} in the vignette documentation.) + +See the vignette \code{vignette("decorate-modules-output", package = "teal")} for additional examples. } \section{\code{server} as a language}{ -Server function in \code{teal_transform_module} must return \code{reactive} containing \link[teal.data:teal_data]{teal.data::teal_data} object. -Consider sinmple transform which doesn't require any advanced reactivity, example \code{server} might have a -following form: +The \code{server} function in \code{teal_transform_module} must return a reactive \code{\link[teal.data:teal_data]{teal.data::teal_data}} object. +For simple transformations without complex reactivity, the \code{server} function might look like this:s \if{html}{\out{
}}\preformatted{function(id, data) \{ moduleServer(id, function(input, output, session) \{ @@ -68,10 +69,10 @@ following form: \} }\if{html}{\out{
}} -Above can be simplified to presented below, where \code{level} will be automatically substituted with -the respective input matched by its name. +The example above can be simplified using \code{make_teal_transform_server}, where \code{level} is automatically matched to the +corresponding \code{input} parameter: -\if{html}{\out{
}}\preformatted{make_transform_data(expr = expression(x <- subset(x, col == level))) +\if{html}{\out{
}}\preformatted{make_teal_transform_server(expr = expression(x <- subset(x, col == level))) }\if{html}{\out{
}} }