Skip to contents

Create teal_module and teal_modules objects

Source: R/modules.R
teal_modules.Rd

[Stable] Create a nested tab structure to embed modules in a teal application.

Usage

module(
  label = "module",
  server = function(id, data, ...) moduleServer(id, function(input, output, session)
    NULL),
  ui = function(id, ...) tags$p(paste0("This module has no UI (id: ", id, " )")),
  filters,
  datanames = "all",
  server_args = NULL,
  ui_args = NULL,
  transformers = list()
)

modules(..., label = "root")

# S3 method for class 'teal_module'
format(x, indent = 0, ...)

# S3 method for class 'teal_module'
print(x, ...)

# S3 method for class 'teal_modules'
format(x, indent = 0, ...)

set_datanames(modules, datanames)

# S3 method for class 'teal_modules'
print(x, ...)

Arguments

label

(character(1)) Label shown in the navigation item for the module or module group. For modules() defaults to "root". See Details.

server

(function) shiny module with following arguments:

  • id - teal will set proper shiny namespace for this module (see shiny::moduleServer()).

  • input, output, session - (optional; not recommended) When provided, then shiny::callModule() will be used to call a module. From shiny 1.5.0, the recommended way is to use shiny::moduleServer() instead which doesn't require these arguments.

  • data (optional) When provided, the module will be called with teal_data object (i.e. a list of reactive (filtered) data specified in the filters argument) as the value of this argument.

  • datasets (optional) When provided, the module will be called with FilteredData object as the value of this argument. (See teal.slice::FilteredData).

  • reporter (optional) When provided, the module will be called with Reporter object as the value of this argument. (See teal.reporter::Reporter).

  • filter_panel_api (optional) When provided, the module will be called with FilterPanelAPI object as the value of this argument. (See teal.slice::FilterPanelAPI).

  • ... (optional) When provided, server_args elements will be passed to the module named argument or to the ....

ui

(function) shiny UI module function with following arguments:

  • id - teal will set proper shiny namespace for this module.

  • ... (optional) When provided, ui_args elements will be passed to the module named argument or to the ....

filters

(character) Deprecated. Use datanames instead.

datanames

(character) Names of the datasets that are relevant for the item. The keyword "all" provides all datasets available in data passed to teal application. NULL will hide the filter panel.

server_args

(named list) with additional arguments passed on to the server function.

ui_args

(named list) with additional arguments passed on to the UI function.

transformers

(list of teal_data_module) that will be applied to transform the data. Each transform module UI will appear in the teal application, unless the custom_ui attribute is set on the list. If so, the module developer is responsible to display the UI in the module itself. datanames of the transformers will be added to the datanames.

When the transformation does not have sufficient input data, the resulting data will fallback to the last successful transform or, in case there are none, to the filtered data.

...

  • For modules(): (teal_module or teal_modules) Objects to wrap into a tab.

  • For format() and print(): Arguments passed to other methods.

x

(teal_module or teal_modules) Object to format/print.

indent

(integer(1)) Indention level; each nested element is indented one level more.

modules

(teal_module or teal_modules)

Value

module() returns an object of class teal_module.

modules() returns a teal_modules object which contains following fields:

  • label: taken from the label argument.

  • children: a list containing objects passed in .... List elements are named after their label attribute converted to a valid shiny id.

Details

module() creates an instance of a teal_module that can be placed in a teal application. modules() shapes the structure of a the application by organizing teal_module within the navigation panel. It wraps teal_module and teal_modules objects in a teal_modules object, which results in a nested structure corresponding to the nested tabs in the final application.

Note that for modules() label comes after ..., so it must be passed as a named argument, otherwise it will be captured by ....

The labels "global_filters" and "Report previewer" are reserved because they are used by the mapping argument of teal_slices() and the report previewer module reporter_previewer_module(), respectively.

datanames

The module's datanames argument determines a subset of datasets from the data object, as specified in the server function argument, to be presented in the module. Datasets displayed in the filter panel will be limited to this subset. When datanames is set to "all", all available datasets in the data object are considered relevant for the module. However, setting datanames argument to "all" might include datasets that are irrelevant for the module, for example:

  • Proxy variables used for modifying columns.

  • Modified copies of datasets used to create a final dataset.

  • Connection objects. To prevent these irrelevant datasets from appearing in the module, use the set_datanames() function on the module or modules() to change the datanames from "all" to specific dataset names. Attempting to change datanames values that was not set to "all" using set_datanames() will be ignored with a warning.

Additionally, datasets with names starting with . are ignored when datanames is set to "all".

Examples

library(shiny)

module_1 <- module(
  label = "a module",
  server = function(id, data) {
    moduleServer(
      id,
      module = function(input, output, session) {
        output$data <- renderDataTable(data()[["iris"]])
      }
    )
  },
  ui = function(id) {
    ns <- NS(id)
    tagList(dataTableOutput(ns("data")))
  },
  datanames = "all"
)

module_2 <- module(
  label = "another module",
  server = function(id) {
    moduleServer(
      id,
      module = function(input, output, session) {
        output$text <- renderText("Another Module")
      }
    )
  },
  ui = function(id) {
    ns <- NS(id)
    tagList(textOutput(ns("text")))
  },
  datanames = NULL
)

modules <- modules(
  label = "modules",
  modules(
    label = "nested modules",
    module_1
  ),
  module_2
)

app <- init(
  data = teal_data(iris = iris),
  modules = modules
)

if (interactive()) {
  shinyApp(app$ui, app$server)
}
# change the module's datanames
set_datanames(module(datanames = "all"), "a")
#> + module

# change modules' datanames
set_datanames(
  modules(
    module(datanames = "all"),
    module(datanames = "a")
  ),
  "b"
)
#> Warning: Not possible to modify datanames of the module module. set_datanames() can only change datanames if it was set to "all".
#> + root
#>  + module
#>  + module