ie_run_app: Assemble and launch a custom isoexplorer app

In isoexplorer: GUI Components to Explore Stable Isotope Data Files

Assemble and launch a custom isoexplorer app

Description

Wraps your own module composition in the isoexplorer navbar shell (theme picker, dark-mode toggle, about popup) and, by default, runs it. Build your layout from the package's modules, instantiate the ie_file_server() and wire the modules in setup_modules. Supply EITHER main (a single content area) OR nav_panels (a centered navbar tabset).

Usage

ie_run_app(
  isofiles,
  main = NULL,
  setup_modules,
  timezone = Sys.timezone(),
  default_theme = app_themes(),
  nav_panels = NULL,
  selected = NULL,
  initial_selection = TRUE,
  upload_folder = NULL,
  monitoring_folders = NULL,
  examples_folder = NULL,
  temporary_storage = FALSE,
  max_upload_size = NULL,
  options = list(),
  uiPattern = "/",
  enableBookmarking = "url",
  detached = FALSE,
  launch = TRUE,
  stop_on_close = detached,
  log_level = c("WARN", "INFO", "DEBUG", "TRACE", "ERROR", "FATAL")
)

Arguments

isofiles	the ir_isofiles to explore (handed to the ie_file_server())
main	a single UI content area (use this OR nav_panels)
setup_modules	⁠function(file, code)⁠ that wires the app's server modules, given the ie_file_server() handle and the ie_code_server() handle (register each module's get_code with code$register()). A one-argument ⁠function(file)⁠ is still accepted (the code server is then not populated).
timezone	timezone for datetime display
default_theme	default bslib Bootstrap 5 theme preset
nav_panels	a list of bslib::nav_panel()s shown as a centered navbar tabset (use this OR main)
selected	the value/title of the nav_panels tab to open initially (NULL = the first tab)
initial_selection	initial file selection, see ie_file_server()
upload_folder	upload directory for the navbar upload button; NULL (the default) means no upload button, see ie_file_server()
monitoring_folders	folders to watch for new isofiles (NULL = off), see ie_file_server()
examples_folder	directory for the "Load examples" navbar button (NULL = off), see ie_file_server()
temporary_storage	note in the upload dialog that uploads are session-only (informational; default FALSE), see ie_file_server()
max_upload_size	maximum per-file upload size in MB; sets the shiny.maxRequestSize option for the running app. NULL (the default) leaves Shiny's ~5 MB default (or a value you set yourself) untouched. Raw isofiles are often larger than 5 MB, so raise this when enabling uploads.
options	Named options that should be passed to the runApp call (these can be any of the following: "port", "launch.browser", "host", "quiet", "display.mode" and "test.mode"). You can also specify width and height parameters which provide a hint to the embedding environment about the ideal height/width for the app.
uiPattern	A regular expression that will be applied to each GET request to determine whether the ui should be used to handle the request. Note that the entire request path must match the regular expression in order for the match to be considered successful.
enableBookmarking	Can be one of "url", "server", or "disable". The default value, NULL, will respect the setting from any previous calls to enableBookmarking(). See enableBookmarking() for more information on bookmarking your app.
detached	if TRUE, the app is launched in a separate R process (via callr::r_bg(), the app handed over in a temporary .rds) and opened in your default browser, leaving the calling session free; closing the browser tab stops the app and the process (which is also killed if the calling session exits). Default FALSE.
launch	only relevant when detached = FALSE: if TRUE (the default) the app is run in the current session (blocking) with shiny::runApp(); if FALSE the shiny::shinyApp() object is returned unrun (for server deployment or manual launching). Ignored when detached = TRUE (a detached app is always run).
stop_on_close	if TRUE, the app stops itself when the browser disconnects (session$onSessionEnded()); set automatically for the detached process so it exits when the tab is closed. Defaults to the same as detached.
log_level	how verbosely the app logs, one of "WARN" (the default – only warnings and errors), "INFO", "DEBUG", "TRACE" (everything), "ERROR", or "FATAL". Sets the LOG_LEVEL environment variable that rlog reads (also applied in the detached process).

Details

The detached / launch arguments control how it runs: detached = TRUE launches it in a separate R process (leaving this session free); ⁠detached = FALSE, launch = TRUE⁠ (the default) runs it in the current session (blocking) with shiny::runApp(); ⁠detached = FALSE, launch = FALSE⁠ returns the shiny::shinyApp() object unrun (for deployment or manual launching). The focused explorers (ie_explore_continuous_flow() etc.) and ie_create_isofiles_server() are wrappers that call this with the appropriate detached / launch.

Value

When detached = TRUE, the callr::r_bg() process (invisibly, with the app URL attached as an attribute); when detached = FALSE and launch = TRUE, the result of shiny::runApp() (after the app stops); when detached = FALSE and launch = FALSE, the shiny::shinyApp() object.

Examples

if (interactive()) {
  # read the bundled isoreader2 examples (a mixed set of all types)
  iso <-
    isoreader2::ir_examples_folder() |>
    isoreader2::ir_find_isofiles() |>
    isoreader2::ir_read_isofiles()

  # a minimal custom app: a scans selector next to a scans plot
  ie_run_app(
    isofiles = iso,
    main = ie_type_explorer_ui("meta", ie_scans_plot_ui("scan")),
    setup_modules = function(file, code) {
      ie_scans_metadata_server("meta", file)
      ie_scans_plot_server("scan", file)
    }
  )
}

isoexplorer documentation built on Sept. 8, 2026, 1:07 a.m.