Getting started with EZRShiny

Starting a new app

createEZApp() makes a folder with a working app in it, ready to edit:

library(EZRShiny)

createEZApp("myApp", appName = "My App")
shiny::runApp("myApp")

The app has an upload page and a results tab with a table. Upload any CSV and click Run to see it work, then replace the pieces with your own.

How an app is laid out

Every EZRShiny app uses the same folder layout:

myApp/
├── app.R               packages, UI and server
├── Functions/          your helper functions, one or more .R files
├── Necessary_Files/    files the app needs at start, such as a data template
└── www/                images for the page, such as logos

app.R is split into numbered sections, so every app reads in the same order:

# App Startup ----
## 1.0 Load Libraries ----
library(shiny)
library(bslib)
library(shinyjs)
library(EZRShiny)

## 2.0 Load Basics ----
options(shiny.maxRequestSize = 300 * 1024^2)   # allow uploads up to 300 MB
sourceFunctions("Functions")                    # load every .R file in Functions/

## 3.0 Universal Vars ----
appName <- "My App"

# UI ----
ui <- UINav(...)

# Server ----
server <- function(input, output, session) { ... }

# Run App ----
shinyApp(ui = ui, server = server)

sourceFunctions() loads every .R file in a folder, so adding a helper is just a matter of saving a new file in Functions/. The files load in alphabetical order, which is why numbering them (1-Read_In_Data.R, 2-Plots.R) is a good habit.

The page

UINav() builds the whole page. Everything else in the UI goes inside it:

ui <- UINav(
  logoFile = "logo.png",   # from the www folder; leave out for no logo
  appName = "My App",      # leave out to use a global appName variable
  barColor = "#1F4E79",    # navigation bar color; leave out for the theme default

  singleTab("Upload", ...),
  biLevelTab("Results", ...)
)

The navigation bar shows, from left to right: the logos, the app name, one entry per tab, and a dark mode switch.

Tabs

Tabs come in two kinds: top-level tabs, which go straight into UINav(), and sub tabs, which go inside a top-level tab.

ui <- UINav(
  appName = "Tab Tour",

  # One page
  singleTab("Upload",
    navUpload("dataUpload", "Upload a CSV")
  ),

  # One page with a sidebar
  sidebarLevelTab("Table",
    sidebarElements = list(
      navSelect("columns", "Columns to show", multiple = TRUE)
    ),
    navOutputTable("dataTable")
  ),

  # A row of sub tabs
  biLevelTab("Plots",
    subSidebarTab("Scatter",
      sidebarElements = list(navButton("makeScatter", "Make plot")),
      navOutputPlot("scatterPlot")
    ),
    subTab("Side by Side",
      subTwoColPage(navOutputPlot("leftPlot"), navOutputPlot("rightPlot"))
    )
  ),

  # A menu of tabs, each with its own sub tabs
  triLevelTab("Models",
    triSubTab("Linear",
      subTab("Fit", navOutputText("linearFit")),
      subTab("Residuals", navOutputPlot("linearResiduals"))
    ),
    triSubSidebarTab("Custom",
      sidebarElements = list(navText("formula", "Model formula")),
      subTab("Fit", navOutputText("customFit"))
    )
  )
)

options(EZRShiny.cardHeight = "70vh")

Inputs

Every input fills the width of its sidebar or page and takes an optional tooltipText, which adds an info icon to the label:

navButton("runData", "Run analysis", tooltipText = "Upload your data first.")

Every input starts with inputId and label, the same as in ‘shiny’. The other arguments use ’shiny’s names too:

multiple = TRUE allows more than one choice or file. create = TRUE lets the user type in options that aren’t in choices.

navSelect("pcX", "PC for x-axis", choices = paste0("PC", 1:10))
navSelect("groups", "Groups to compare", choices = groupNames, multiple = TRUE)
navSelect("tags", "Tags", choices = c("a", "b"), multiple = TRUE, create = TRUE)

Choices for navSelect() can be left out of the UI and filled in from the server once data is loaded:

# UI
navSelect("groups", "Pick groups", multiple = TRUE)

# Server
updateSelectizeInput(session, "groups", choices = unique(theData$Group))

navSpanText() adds a line of text with an info icon, for explaining a page.

Outputs

Each output is a placeholder the server fills in with the matching render function:

Like inputs, outputs can have a label shown above them and a tooltipText that adds an info icon after the label. Use it to explain how to read a plot or table. With a tooltip and no label, only the icon is shown.

navOutputPlotly("pcaPlot", label = "PCA of all samples",
                tooltipText = "Each point is one sample, colored by group.")

The server

The server of an EZRShiny app follows a few habits that keep it predictable.

Keep the user’s data in one place. Store anything that needs to carry across the app in one reactiveValues() list:

global <- reactiveValues(
  datasets = list(
    rawData = NULL
  )
)

Set up the page on start. Hide tabs and switch off buttons and downloads that can’t be used yet:

observe({
  startSection("Run on Start")

  hideNavTabs(rootID = "Results", tabIDs = c("Table", "Plot"))
  deactivateItems(c("runAnalysis", "resultsDownload"))

  endSection("Run on Start")
})

Tie work to buttons. Code in observeEvent(input$button, ...) runs only when the button is clicked. Code that reads inputs anywhere else reruns every time any of those inputs change.

observeEvent(input$runAnalysis, {
  startSection("Run Analysis")

  ## Load globals
  rawData <- global$datasets$rawData

  ## Inputs
  alpha <- input$alpha

  ## Do things
  results <- runMyAnalysis(rawData, alpha)

  ## App interactions
  output$resultsTable <- DT::renderDT({ results })
  activateItems(c("resultsDownload"))
  showNavTabs(rootID = "Results", tabIDs = c("Table", "Plot"))
  nav_select("root", "Results")

  ## Save globals
  global$datasets$results <- results

  endSection("Run Analysis")
})

The example app

EZRShiny comes with a complete example app, “Titanic Explorer”, that explores who survived the Titanic using R’s built-in Titanic data:

runExampleApp()

It uses every piece described above:

Every tab except Load Data is hidden until data is loaded, and each download is switched off until there’s something to download. Its files are a good starting point for your own app:

exampleFolder <- system.file("examples", "titanicExplorer", package = "EZRShiny")
list.files(exampleFolder, recursive = TRUE)
file.copy(exampleFolder, "myCopy", recursive = TRUE)

Moving an existing app to EZRShiny

If your app sources a copy of the standards file from its Functions folder:

1. Delete the standards file from Functions/. The package replaces it.

2. Replace its source(...) line with library(EZRShiny). Keep sourceFunctions("Functions") to load your other helpers.

3. Move options(shiny.maxRequestSize = ...) into app.R if you need uploads over 5 MB. The package doesn’t change options for you.

4. Logos and colors are now arguments of UINav() instead of being built in:

   ui <- UINav(
     logoFile = c("institute_logo.png", "app_logo.png"),
     logoHeight = c("35vh", "40vh"),
     appName = appName,
     barColor = "#005596",
     ...
   )

5. cardHeight is no longer a global variable. Use options(EZRShiny.cardHeight = "85vh") or each tab’s height argument.

6. Inputs take TRUE/FALSE instead of short words, and their arguments use ’shiny’s names. Calls with only an ID, a label and tooltipText don’t change. The rest change like this:

   Before	After
   navSelect("id", "Label", "Single", "Locked", choices)	navSelect("id", "Label", choices)
   navSelect("id", "Label", "Multi", "Locked", choices)	navSelect("id", "Label", choices, multiple = TRUE)
   navSelect("id", "Label", "Single", "Create", choices)	navSelect("id", "Label", choices, create = TRUE)
   navUpload("id", "Label", "Single")	navUpload("id", "Label")
   navUpload("id", "Label", "Multi")	navUpload("id", "Label", multiple = TRUE)
   navCheckbox("id", "Label", "T")	navCheckbox("id", "Label", value = TRUE)
   navCheckbox("id", "Label", "F")	navCheckbox("id", "Label")
   navNumeric("id", "Label", 5)	unchanged, but min and max now default to no limit instead of 0 and 1
   navNumeric(..., theValue = 5)	navNumeric(..., value = 5)
   navColor(..., colorValue = "red")	navColor(..., value = "red")
   navDate("id", "Label", TRUE)	navDate("id", "Label", range = TRUE)

   Passing an old short word such as "Single" where TRUE or FALSE is expected stops with an error that explains the change.