Obtain the module information — module

current_module returns the information of the currently running module. It looks up the .module_id variable in the calling environment (set automatically when a module is loaded), then retrieves the corresponding row from the module table.

active_module returns a reactive value with information about the module that is currently visible in the iframe tab (or the standalone module if no iframe manager is present). Unlike current_module which is static and always returns the module whose server code is running, active_module dynamically tracks which module the user is looking at from any context.

switch_module shows a module in the dashboard, as clicking it in the sidebar does: the module's open tab comes to the front, or the module opens in a new tab. It sends a shidashi.switch_module message to the JavaScript front-end. When called from a module running inside an iframe, the page asks the dashboard in its parent frame to switch, so that the sidebar highlight, tab bar, and iframe all update correctly.

Usage

module_info(root_path = template_root(), settings_file = "modules.yaml")

current_module(
  session = shiny::getDefaultReactiveDomain(),
  root_path = template_root()
)

active_module(
  session = shiny::getDefaultReactiveDomain(),
  root_path = template_root()
)

switch_module(
  module_id,
  session = shiny::getDefaultReactiveDomain(),
  auto_new = TRUE
)

load_module(
  root_path = template_root(),
  request = list(QUERY_STRING = "/"),
  env = parent.frame()
)

Arguments

root_path: the root path of the website project
settings_file: the settings file containing the module information
session: shiny reactive domain; used to extract the module id from the URL query string when .module_id is not found.
module_id: character string; the target module identifier (must match an entry in modules.yaml).
auto_new: logical; whether to open the module in a new tab when it is not open; FALSE only switches to an open tab.
request: 'HTTP' request string
env: environment to load module variables into

Value

A data frame with the following columns that contain the module information:

id: module id, folder name
order: display order in side-bar
group: group menu name if applicable, otherwise NA
label: the readable label to be displayed on the side-bar
icon: icon that will be displayed ahead of label, will be passed to as_icon
badge: badge text that will be displayed following the module label, will be passed to as_badge
url: the relative 'URL' address of the module.

current_module: a named list with id, group, label, icon, badge, and url of the current module, or NULL if no module is active.

active_module: a named list with id, group, label, icon, badge, and url of the currently active (visible) module, or NULL if no module is active.

Details

The module files are stored in modules/ folder in your project. The folder names are the module id. Within each folder, there should be one "server.R", R/, and a "module-ui.html".

The R/ folder stores R code files that generate variables, which will be available to the other two files. These variables, along with some built-ins, will be used to render "module-ui.html". The built-in functions are

ns: shiny name-space function; should be used to generate the id for inputs and outputs. This strategy avoids conflict id effectively.
.module_id: a variable of the module id
module_title: a function that returns the module label

The "server.R" has access to all the code in R/ as well. Therefore it is highly recommended that you write each 'UI' component side-by-side with their corresponding server functions and call these server functions in "server.R".

active_module works by reading the '@shidashi_active_module@' Shiny input that is set by the JavaScript front-end whenever a module tab is activated. Because it accesses session$rootScope()$input, the return value is reactive: when called inside an observe or reactive context it will re-fire whenever the user switches modules.

If the input has not been set yet (e.g. before any module is opened), the function falls back to current_module().

Examples


library(shiny)
module_info()
#>                   id   group           label                 icon badge
#> 1         getstarted    <NA>     Get Started               rocket      
#> 2               card   Cards           Cards               square      
#> 3            widgets   Cards         Widgets         puzzle-piece      
#> 4            aiagent  Agents   AI Agent Demo                robot      
#> 5           mcpsetup  Agents MCP Setup Guide                 plug      
#> 6     output_widgets Widgets  Output Widgets    external-link-alt      
#> 7               demo    <NA>            Demo            chart-bar      
#> 8      filestructure    <NA>  File Structure          folder-open      
#> 9            page500    <NA>       Error 500 exclamation-triangle      
#> 10        stream_viz Widgets      Stream Viz          wave-square      
#> 11    session_events Widgets  Session Events      broadcast-tower      
#> 12 standalone_viewer    <NA>                                           
#>                           url
#> 1         /?module=getstarted
#> 2               /?module=card
#> 3            /?module=widgets
#> 4            /?module=aiagent
#> 5           /?module=mcpsetup
#> 6     /?module=output_widgets
#> 7               /?module=demo
#> 8      /?module=filestructure
#> 9            /?module=page500
#> 10        /?module=stream_viz
#> 11    /?module=session_events
#> 12 /?module=standalone_viewer

# load master module
load_module()
#> $environment
#> <environment: 0x5570b3065558>
#> 
#> $has_module
#> [1] FALSE
#> 
#> $root_path
#> [1] "/home/runner/.local/share/R/shidashi/bslib-bare"
#> 
#> $template_path
#> [1] "/home/runner/.local/share/R/shidashi/bslib-bare/index.html"
#> 
#> $module
#> $module$id
#> NULL
#> 
#> $module$server
#> function (input, output, session, ...) 
#> {
#> }
#> <bytecode: 0x5570b46b0028>
#> <environment: 0x5570b46b10d8>
#> 
#> $module$template_path
#> NULL
#> 
#> 

# load specific module
module_data <- load_module(
  request = list(QUERY_STRING = "/?module=module_id"))
env <- module_data$environment

if (interactive()) {

# get module title
env$module_title()

# generate module-specific shiny id
env$ns("input1")

# generate part of the UI
env$ui()

}