document shiny app functions

inst/eDISH_app/modules/dataUpload/dataUpload.R

@@ -1,3 +1,32 @@
+#' Data upload module - server code
+#'
+#' This module creates the Data tab for the Shiny app. 
+#' 
+#' Workflow:
+#' (1) A reactiveValues() list is created with example dataset as first entry. 
+#'     The following information is included in list:
+#'        - dataset and name
+#'        - current (whether the dataset came from most recent upload)
+#'        - data standard / quality of match
+#' (2) Upon user data upload:
+#'        - reactiveValues list is updated with information about new data.
+#'        - radio buttons are updated with new data choices
+#' (3) When a new dataset is selected, the data preview output is invalidated
+#' (4) When a new dataset is selected OR the standard changes (since these don't update at the same time), the
+#'     the settings object ("settings()") is invalidated.
+#' (5) When a new dataset is selected OR the settings object is updated, the settings validation ("status()") is 
+#'     invalidated.
+#' 
+#' @param input Input objects from module namespace
+#' @param output Output objects from module namespace
+#' @param session An environment that can be used to access information and functionality relating to the session
+#'
+#' @return A list of reactive values, including: 
+#' \itemize{
+#' \item{"data_selected"}{A data frame selected by the user}
+#' \item{"settings"}{Result from generateSettings() for data_selected}
+#' \item{"status"}{Result from validateSettings() for data_selected and settings}
+#'  
 dataUpload <- function(input, output, session){
 
   ns <- session$ns

inst/eDISH_app/modules/dataUpload/dataUploadUI.R

@@ -1,3 +1,16 @@
+#' Data upload module - UI code
+#' 
+#' This module creates the Data tab for the Shiny app. 
+#' 
+#' The UI contains:
+#' - a file upload control
+#' - radio buttons for selecting from the available datasets
+#' - raw data preview. 
+#'
+#' @param id The module-specific ID that will get pre-pended to all element IDs
+#'
+#' @return The UI for the Data tab
+#'
 dataUploadUI <- function(id){
 
   ns <- NS(id)

inst/eDISH_app/modules/renderChart/renderEDishChart.R

@@ -1,3 +1,19 @@
+#' Render eDISH chart - server code
+#' 
+#' This module creates the Chart tab for the Shiny app, which contains the interactive eDISH graphic. 
+#' 
+#' Workflow: 
+#' (1) A change in `data`, `settings`, or `valid` invalidates the eDISH chart output
+#' (2) Upon a change in `valid`, the export chart functionality is conditionally made available or unavailable to user
+#' (3) If "export chart" button is pressed, data and settings are passed to the parameterized report, knitted using
+#'     Rmarkdown, and downloaded to user computer.
+#' 
+#' @param input Input objects from module namespace
+#' @param output Output objects from module namespace
+#' @param session An environment that can be used to access information and functionality relating to the session
+#' @param data A data frame 
+#' @param valid A logical indicating whether data/settings combination is valid for chart
+
 renderEDishChart <- function(input, output, session, data, settings, valid){
 
   ns <- session$ns

inst/eDISH_app/modules/renderChart/renderEDishChartUI.R

@@ -1,3 +1,11 @@
+#' Render eDISH chart - UI code
+#' 
+#' This module creates the Chart tab for the Shiny app, which contains the interactive eDISH graphic.  
+
+#' @param id The module-specific ID that will get pre-pended to all element IDs
+#'
+#' @return The UI for the Chart tab
+#'
 renderEDishChartUI <- function(id){
 
   ns <- NS(id)

inst/eDISH_app/modules/renderSettings/renderSettings.R

@@ -1,8 +1,49 @@
+# Functions to include
 source("modules/renderSettings/util/createSettingLabel.R")
 source("modules/renderSettings/util/createControl.R")
 source("modules/renderSettings/util/createSettingsUI.R")
 source("modules/renderSettings/util/updateSettingStatus.R")
 
+#' Render Settings module - Server code
+#' 
+#' This module creates the Settings tab for the Shiny app. 
+#'  
+#' Workflow:
+#' (1) Reactive input_names() contains names of settings related to selected charts.  When a user changes
+#'     chart selections, input_names() is invalidated.
+#' (2) A change in input_names(), `data`, or `settings` invalidates the following:
+#'      - renderUI associated with data mapping settings
+#'      - renderUI associated with measure settings
+#'      - renderUI associated with appearance settings
+#' (3) These renderUI's call upon the createSettingsUI() function and will update
+#'     even when settings tab not in view.  They will create and populate the UI for all related settings.
+#' (4) Field-level inputs are updated upon any of the following events:
+#'      - a change in selected data
+#'      - change in selected chart(s)
+#'      - change in column-level input selection
+#'     update includes:
+#'      - Deactivate/activate field-level selector based on whether column-level input has been selected
+#'      - Data choices for field-level inputs based on selected column-level input
+#'  (5) A reactive representing the new settings object (settings_new()) is created based on UI selections. This object is invalidated
+#'      when ANY input changes.
+#'  (6) A reactive representing the new data/settings validation (status_new()) is created based on data and updated settings object.  
+#'      A change in data OR updated settings object invalidated this reactive.
+#'  (7) Upon a change in the new validation (status_new() and derived status_df()), updated status messages are 
+#'      printed on UI by calling updateSettingStatus().  ALL messages are re-printed at once.
+#'     
+#' @param input Input objects from module namespace
+#' @param output Output objects from module namespace
+#' @param session An environment that can be used to access information and functionality relating to the session
+#' @param data A data frame
+#' @param settings Settings object that corresponds to data's standard - result of generateSettings().
+#' @param status A list describing the validation state for data/settings - result of validateSettings().
+#'
+#' @return A list of reactive values, including: 
+#' \itemize{
+#' \item{"charts"}{A vector of chart(s) selected by the user}
+#' \item{"settings"}{Upadted settings object based on UI/user selections}
+#' \item{"status"}{Result from validateSettings() for originally selected data + updated settings object}
+#' 
 renderSettings <- function(input, output, session, data, settings, status){
 
   ns <- session$ns
@@ -199,14 +240,14 @@ renderSettings <- function(input, output, session, data, settings, status){
   # print validation messages
   ######################################################################
  observe({
-   for (name in isolate(input_names())){
+   for (key in isolate(input_names())){
 
-     if(name %in% status_df()$text_key){
+     if(key %in% status_df()$text_key){
 
-       status_short <- status_df()[status_df()$text_key==name, "message_short"]
-       status_long <- status_df()[status_df()$text_key==name, "message_long"]
+       status_short <- status_df()[status_df()$text_key==key, "message_short"]
+       status_long <- status_df()[status_df()$text_key==key, "message_long"]
 
-       updateSettingStatus(ns=ns, name=name, status_short=status_short, status_long=status_long)
+       updateSettingStatus(ns=ns, key=key, status_short=status_short, status_long=status_long)
      }
 
    }

inst/eDISH_app/modules/renderSettings/renderSettingsUI.R

@@ -1,4 +1,18 @@
-
+#' Render Settings module - UI code
+#' 
+#' This module creates the Settings tab for the Shiny app. The UI is dynamically populated from the server side. 
+#' 
+#' The UI contains:
+#' - Chart selector 
+#' - Settings customizations for the selected charts:
+#'      - Data mapping
+#'      - Measure settings
+#'      - Appearance settings
+#'
+#' @param id The module-specific ID that will get pre-pended to all element IDs
+#'
+#' @return The UI for the Settings tab
+#'
 renderSettingsUI <- function(id){
 
   ns <- NS(id)

inst/eDISH_app/modules/renderSettings/util/createControl.R

@@ -1,3 +1,21 @@
+#' Create setting control 
+#'
+#' Workflow:
+#' (1) Get setting label and description from metadata
+#' (2) Get setting value from settings object
+#' (3) Get choices and placeholder text for the selectors based on metadata, data, and settings
+#' (4) Create HTML code for the selector based on the following metadata:
+#'     - whether the option is a column or field-level input
+#'     - data type of the setting (e.g. character/numeric/logical, vector of length 1 vs >1) 
+#'     - label, description, choices, selected value, placeholder text
+#' 
+#' @param key A character key representing the setting of interest  
+#' @param metadata Metadata data frame to be queried for information about the setting
+#' @param data A data frame to be used to populate control options
+#' @param settings A settings list to be used to populate control options
+#' @param ns  The namespace of the current module
+#'
+#' @return HTML code for the div containing the setting of interest
 createControl <- function(key, metadata, data, settings, ns){
 
   sm_key <- filter(metadata, text_key==key)

inst/eDISH_app/modules/renderSettings/util/createSettingLabel.R

@@ -1,3 +1,10 @@
+#' Create label for chart setting selector
+#'
+#' @param key A character key representing the setting of interest.
+#'
+#' @return A character string containing full HTML text to be used for input label. Contains info icon to 
+#' indicate that description is available upon mouseover, setting label, and asterisk if setting is required.
+#' 
 createSettingLabel <- function(key){
   sm <- getSettingsMetadata(text_keys=key)
   setting_label <- sm$label

inst/eDISH_app/modules/renderSettings/util/createSettingsUI.R

@@ -1,3 +1,12 @@
+#' Create UI for specified section of settings tab
+#'
+#' @param data A data frame to be used to populate control options
+#' @param settings A settings list to be used to populate control options
+#' @param setting_cat_val Settings category. One of "data","measure","appearance"
+#' @param charts A character vector containing names of charts of interest
+#' @param ns The namespace of the current module
+#'
+#' @return A list containing the UI code for all selectors in the specified settings category.
 createSettingsUI <- function(data, settings, setting_cat_val, charts, ns){
 
   sm <- getSettingsMetadata(charts=charts) %>% 

inst/eDISH_app/modules/renderSettings/util/updateSettingStatus.R

@@ -1,7 +1,18 @@
-updateSettingStatus<-function(ns, name, status_short, status_long){
+#' Update setting validation status
+#' 
+#' Workflow:
+#' (1) Update abbreviated status for a given setting using green (valid) or red (invalid) text
+#' (2) Update long status message for a given setting to be displayed upon mouseover
+#' 
+#' @param ns The namespace of the current module
+#' @param key A character key representing the setting of interest 
+#' @param status_short Abbreviated validation message  
+#' @param status_long Detailed validation message  
+
+updateSettingStatus<-function(ns, key, status_short, status_long){
 
-  msg_id <- paste0("msg_", name)
-  tooltip_id <- paste0("tt_msg_", name)
+  msg_id <- paste0("msg_", key)
+  tooltip_id <- paste0("tt_msg_", key)
 
   if (status_short=="OK"){
     shinyjs::html(id = msg_id,

inst/eDISH_app/server.R

@@ -1,3 +1,10 @@
+# Server code for safetyGraphics App
+#   - calls dataUpload module (data tab)
+#   - calls renderSettings module (settings tab)
+#   - calls renderEDishChart (chart tab)
+#   - uses render UI to append a red X or green check on tab title, 
+#      indicating whether user has satisfied requirements of that tab
+
 function(input, output, session){
 
 

inst/eDISH_app/ui.R

@@ -1,3 +1,5 @@
+# UI Code for safetyGraphics App
+
 tagList(
   useShinyjs(),
   tags$style(HTML("